UserDB

UserDB is a first party data store that enables you to activate on user-level targeting. UserDB can serve as an activation destination for any segmentation tool.

Overview

UserDB is a server-side data store that Kevel customers can use for user level targeting and ad optimization.

๐Ÿ“˜

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.

Major use cases include:

Use CaseExample
Interest / Behavioral Targeting = Build segments based on users' interests and past behavior so as to offer highly-valuable targeting options to advertisersKevel records when a user clicks on ads for beauty products. You can then create a segment (comprised of those clickers) called 'Beauty Product Users' and sell that to advertisers for a premium.
Demographic / Custom Properties Targeting = Build segments based on user-given information (ex: demographic data like age/gender) and then offer that as targeting options to advertisersWhen a user completes a sign-up form, you send that info to UserDB - such as age, gender, and location. Moving forward you can let advertisers target that data, like "gender = male" or "age > 25"
Frequency capping = Only show ads a certain number of times over a certain time periodJohn will see only one ad from Febreeze's August Flight every hour.
Excluding Ads Based on Behavior = Record what ads a user has clicked on and stop showing ads from the same Flight or AdvertiserJohn doesn't see another ad from Febreeze after clicking on one of their ads
Retargeting = Let advertisers retarget people who have visited their own siteFebreeze can target someone who visited their site when the same person is on your site
RTB partner user IDs = For use with real-time-bidding campaignsUsed for user matching to increase value of the ad impression
Managing GDPR Consent = Store whether a user has given consent or notYou having a GDPR prompt and want to update UserDB that the user has said 'yes' to sharing their data

๐Ÿ“˜

Note

An additional benefit of UserDB is that it cuts down on data sent in the ad request - making it particularly useful for app developers who care about battery/bandwidth usage, as you only have to pass "key": "ad39231daeb043f2a9610414f08394b5", versus a ton of additional data in each ad request.

How It Works

All records in UserDB are tied to a userkey - which is a unique, persistent identifier associated with a given user. To this userkey is tied interest, behavior, demographic data, as well as information like how many times they saw an ad.

This ID is either created by you or created by Kevel if you have not included one in the request.

Then, when that ID is passed in the Decision API request, Kevel will cross-reference that userkey with UserDB and incorporate that information as needed into deciding which ad to show.

๐Ÿšง

Caution

UserDB only works if you are able to store the userkey on your side and pass it in the ad request for that user every time!

Creating the UserKey

๐Ÿ“˜

Note

The UserKey must be in string format

There are a few options:

Persistent ID
You create: Internal proprietary identifier (such as a hashed e-mail address)
You pull: Mobile Identifiers (iOS IDFA; Android GAID)
Kevel creates: If the user field is blank in the ad request, Kevel will generate a random GUID and send it back in the Decision API Response. You'll then need to store it.

โ—๏ธ

Warning

For privacy reasons, do not send anything that's PII (personally identifiable information).

Storing and Sending the UserKey

How you store it is up to you! But make sure when you send a Decision API request, you are passing it in the user object.

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

โ—๏ธ

Warning

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

๐Ÿ“˜

Add an extra layer of security by requiring a valid API key for UserDB requests

Contact Support and ask for the below feature flag to be enabled:

userdbAuthRequired - Once enabled, requests to UserDB will not succeed without a valid API key sent in with the request.

๐Ÿšง

Caution

If you do not include the userkey or have a different one every time, there is no way we will be able to match the user to a record in UserDB.

The UserDB Record

For each UserDB record, you'll have the following information.

DataDescriptionExample
key (string)The unique ID associated with that user. (Max 1024 characters.)"key":"ue1-e397eb5990c041858071b63ca5bcc00c"
isNew (boolean)If true, the user record has just been created. isNew will always be set to false on retrieved records."isNew":false
interests (array of strings)Lists their Flight Category interests. See here for more info on interest targeting."interests":[ "news", "sports" ] }
custom (object)Contains custom JSON uploaded by you. Used for demographic/custom targeting."custom":{ "anything": "goes", "lookAtMe": [ "itsAnArray", 42 ] }
retargetingSegments (object)Lists the retargeting segments the user belongs to. The keys are "b" plus the Advertiser ID in Kevel. The values retargeting segment ID. More informaiton about retargeting can be found here."retargetingSegments":{ "b12345": [ 2, 3, 4 ] }
blockedItems (object)Lists the IDs of objects that settings have blocked from serving to the user. "blockedItems":{ "advertisers":[ 1234, 1235 ], "campaigns":[ 12345, 12346 ] }
flightViewtimes (object)Lists frequency-capped flights that a user has viewed. Each flight contains an array of strings with ISO 8601 timestamps of when the view occurred. "flightViewTimes":{ "123456": [ "2015-12-03T16:57:39.000Z", "2015-11-21T20:53:44.000Z", "2015-12-08T16:43:47.000Z", "2015-11-18T14:12:05.000Z" ] }
adViewtimes (object)Lists frequency-capped ads that a user has viewed. Each ad contains an array of strings with ISO 8601 timestamps of when the view occurred."adViewTimes":{ "789012": [ "2015-12-03T16:57:39.000Z", "2015-12-08T16:43:47.000Z", "2015-11-21T20:53:43.000Z" ] }
partnerUserIds (object)Used for user matching with RTB partners. The keys are the partner ID in Kevel and the values are arrays of strings that contain the IDs."partnerUserIds":{ "p1": [ "0shj0we09hw" ] }
optOut (boolen)If true, the user has opted out of data collection by UserDB. In that case, all other parameters will be deleted except for the userKey and the optOut setting, and the parameters cannot be written to in the future."optOut":false
consent (object)Sets consent, important for indicating GDPR Consent. You can set it with our GDPR Consent API Endpoint."consent": { "gdpr": true }
ip (string)The IP address of the user if overridden using the IP Override endpoint below."ip": "10.10.10.10"
{
   "key":"ue1-e397eb5990c041858071b63ca5bcc00c",
   "isNew":false,
   "interests":[
      "news",
      "sports"
   ],
   "blockedItems":{
      "advertisers":[
         1234,
         1235
      ],
      "campaigns":[
         12345,
         12346
      ],
      "creatives":[
         123456,
         123457
      ],
      "flights":[
         234567,
         234568
      ]
   },
   "flightViewTimes":{
    "123456": [
      "2015-12-03T16:57:39.000Z",
      "2015-11-21T20:53:44.000Z",
      "2015-12-08T16:43:47.000Z",
      "2015-11-18T14:12:05.000Z"
    ]
   },
   "adViewTimes":{
    "789012": [
      "2015-12-03T16:57:39.000Z",
      "2015-12-08T16:43:47.000Z",
      "2015-11-21T20:53:43.000Z"
    ]
   },
   "siteViewTimes":{

   },
   "pendingConversions":[

   ],
   "partnerUserIds":{
    "p1": [
      "0shj0we09hw"
    ]
   },
   "retargetingSegments":{
    "b12345": [
      2,
      3,
      4
    ]
   },
   "custom":{
    "anything": "goes",
    "lookAtMe": [
      "itsAnArray",
      42
    ]
   },
   "consent": {
    "gdpr": true
  },
   "optOut":false,
   "dirtyCookies":{

   },
  "ip": "10.10.10.10"
}

โ—๏ธ

Warning

The maximum size of a custom data object in a UserDB record is 8 KB.

Creating/Updating a New UserDB Record

This happens in one of two ways:

  1. When Kevel receives an ad request, where applicable we automatically create or update the UserDB record (such as updating interests and adviewtimes)
  2. You can ping UserDB directly via one of our UserDB API Endpoints

๐Ÿ“˜

Note

Hitting our endpoints directly is effective if you want to send data during a registration process, to bulk upload historical data, or to update a row based on an action outside of an ad request (such as consenting to data sharing).

Pulling the UserDB Data On a User

You'll want to use our Read a User's UserDB Record API Endpoint.

Targeting Against UserDB Data

Please refer to our step-by-step guides on how to target by the different UserDB fields, based on your goal:

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