UserDB Tutorial (Interests)

Overview

UserDB is your turnkey data store. It lets you tie information to a specific user, build segments off of this data, and then use those segments for:

1. Internal optimizations
2. Additional targeting options for advertisers, usually at a premium price

You can learn more by visiting our API page and our Knowledge Base page.

Getting Started

UserDB only works if you can (1) store a persistent ID associated with each user on your side, (2) identify that user at time of ad impression and (3) pass that in the Decision API request.

In this tutorial, we will be assuming that you are creating persistent IDs yourself. Some common options include:

Adding an Interest to a User with Behavioral Tracking

Interest targeting refers to targeting a user based on topics they are interested in. With the Behavioral method, Kevel tracks the type of ads users click/convert on, and, if behavioral tracking is enabled, these users are added to the relevant segment.

For this tutorial, we'll continue to use the Test Campaign/Test Flight created in the Decision API Quickstart. That said, feel free to use any Campaign you'd like. We'll also use the UI to set up campaigns for the sake of simplicity, but if you feel comfortable building Flights with the Management API, please do.

📘

Make sure to clear out any Custom or Keyword Targeting rules you may have set from the previous tutorials

📘

UserDB is optimized for low latency

UserDB was built to focus on low latency lookups at the time of the ad decision request, and high data reliability. In order to achieve this, UserDB is only indexed on the user key. However, this indexing method means that UserDB does not provide an aggregated view of users based on attributes. For this feature, as well as the ability to gain insight into user behavior and create machine learning-driven audiences, Kevel suggests connecting UserDB with an audience segmentation tool. To ensure smooth integration, Kevel recommends using Kevel Audience, which is a powerful tool for audience segmentation and management.

Set up with UI

1. Edit the "Test Flight" Flight from the Quickstart

2. Go to the Behavioral Targeting section

3. Check the 'clicks' box in the "When a user clicks on an ad from this flight store this flight's categories as an interest for them" row

4. Type in a category, eg. "shoes"

   

5. Save flight

Click on the Ad

7. Make a Decision API request for a placement. The Decision API Quickstart offers details on that

8. Include all the right IDs:
   "networkid" - e-mail support
   "siteID" - go to the Sites tab and grab the ID next to the site name (this will be 'Web' if following the Decision API Quickstart guide)
   "campaignID" - go to the Campaigns tab and grab the ID next to the Test Campaign

9. Under key, use "12345". Technically you can use any number you want.

10. Send the request

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16],
      "campaignId":"**Your Campaign ID**"
    }
  ],
   "user" : {
    "key": "12345"
  },
}

curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXXX,"siteId":XXXX,"campaignId":XXX,"adTypes":[16]}],"user":{"key":"12345"}}' https://e-<networkId>.adzerk.net/api/v2

11. In the response you'll get a clickURL. Grab this and "click" it by visiting the link in your browser

👍

The UserKey you just used should now be added to the Interest Segment of 'Shoes'!

Adding an Interest to a User with API Directly

Interest targeting doesn't have to be based on ad clicks. In fact, it could be advantageous to send info you've collected from organic content and 1st party data directly to UserDB.

For instance, you could record on your side when a user clicks on an organic content for "shoes" and then send that to be stored in UserDB. Otherwise, Kevel would have no knowledge that the user has an interest in shoes (unless they clicked on a shoe ad).

This method is quite easy and skips steps #1-#11. It involves the Add Interest to a User Endpoint. You'll just need your Network ID and the userKey.

Validating the User Now Has That Interest

Now, let's use the API to access UserDB and see if your UserKey is in the segment.

1. You'll want to GET the Read a User's UserDB Record Endpoint using the correct userKey

2. The corresponding output will have lots of information, but you should look for just the interest object.

{
   "key":"ue1-e397eb5990c041858071b63ca5bcc00c",
   "isNew":false,
   "interests":[
      "shoes"
   ],
   .......

Targeting The Shoes Interest Category

Setting It Up

1. Edit the "Test Flight" flight
2. Go to the Custom Targeting section
3. In the box, write $user.interests contains "shoes"
4. Save
5. Make sure this is the only active Flight in the Campaign

📘

This Zerkel Query uses Reserved Keys to target the Interest Segment. Specifically, a Reserved Key of $user.interests paired with a Zerkel Query operator and the key's value.

Make Another Decision API Request

1. Make another placement request to Kevel using the campaign's ID. You'll want to do two tests:

a. Send a request WITHOUT the 12345 userKey. If set up correctly, no ad should be in the response
b. Send a request WITH the user key. If set up correctly, the test campaign should provide a response

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16],
      "campaignId":"**Your Campaign ID**"
    }
  ],
   "user" : {
    "key": "12345"
  },
}

curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXXX,"siteId":XXXX,"campaignId":XXX,"adTypes":[16]}],"user":{"key":"12345"}}' https://e-<networkId>.adzerk.net/api/v2

👍

Congratulations! You've successfully discovered how to add an interest to a user, as well as how to target them.