UserDB

📘

If your Kevel account uses a CNAME for e-.adzerk.net, you must use your CNAMEd domain for reading and writing to UserDB endpoints.

Overview

User-level targeting refers to targeting that knows information about the particular individual seeing the ad. This data is tied to a persistent ID called the UserKey, which is passed in the key value of the user object of the Decision API request. This information is stored in Kevel's UserDB in JSON format.

The main uses cases of user-level targeting are:

Interest / Behavioral Targeting
Excluding Ads Based on Behavior
Demographic / Custom Properties Targeting
Retargeting / Segment Targeting

Passing the UserKey

For user-level targeting to work, you'll need to send the same persistent UserKey ID as the key value in the user object in the Decision API request ever time the user sees an ad.

Kevel will cross-reference this UserKey with UserDB and see if there's a record associated with the User. If there is a match, this information will be used by the Ad Decision Engine to pick the right ad, based on what type of user-level targeting you have set up.

An example Decision Request with a Userkey (key) included is:

{
  "placements": [
    {
      "divName": "homepage",
      "networkId": 23,
      "siteId": 667480,
      "adTypes": [5],
      "eventIds": [12,13,14]
    }
  ],
  "user" : {
    "key": "ad39231daeb043f2a9610414f08394b5"
  }
}

❗️

The UserDB API can be accessed without an API key, so you shouldn't use vulnerable User ID to represent your users in UserDB.

For added security, Kevel has the option to require API Key authentication for the UserDB API. Please reach out to your CSM or [email protected]to enable.

For more on authenticating requests, see this page.

👍

Note that the user key supplied in the user object will override a user key set via the azk cookie.

🚧

If you are recording data and using that for segments, you may need to update your terms with advertisers to reflect this.

🚧

Remember: for user-level targeting to work, you will need to pass the persistent UserKey in the user object's key field of the Decision API request. If you send the UserKey, Kevel's Ad Decision Engine will cross-reference with UserDB when picking the right ad. However, if you are not sending UserKeys - or not using persistent IDs - Kevel will not be able to match anything to UserDB and user-level targeting won't work.

UserDB Logs and Properties

Logs of your account's UserDB endpoint activity can be made available via data shipping. In addition to UserDB endpoints, userKeys and payloads, the logs can contain arbitrary properties set on the endpoints. These are key/value pairs that you can use to track metadata about the request (like a version number, for instance) that will persist after the request is complete. All UserDB endpoints support properties.

For example, if you wanted to track a version number and a nickname when a userKey is loaded via the azk cookie, you would append those via two property: query parameters:

https://e-1234.adzerk.net/udb/1234/set/i.gif?userKey=abc123&property:version=1&property:nickname=George

The resulting logs will include those properties:

{
  "Meta:schema": "userdb",
  "Meta:version": "1.0",
  "NetworkId": 1234,
  "Timestamp": 1539104456290,
  "Action": "cookie",
  "UserKey": "abc123",
  "Properties": {
    "version": "1",
    "nickname": "George"
  }
}

👍

Up to 10 properties can be set per request. A maximum of 1KB of properties can be set per request.