UserDB

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:

📘

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:

❗️

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.

{
   "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