The Adzerk Developer Hub

Welcome to the Adzerk developer hub. You'll find comprehensive guides and documentation to help you start working with Adzerk as quickly as possible, as well as support if you get stuck. Let's jump right in!

UserDB

UserDB is your first-party data management platform that enables you to do user-level targeting, such as targeting by demographics, interests, etc, as well as do retargeting and frequency capping.

UserDB is a feature in the Business and Enterprise plans. To learn more about the UserDB API Endpoints, click here.

Overview

UserDB is a server-side data management platform that Adzerk customers can use for advanced targeting and ad optimization.

Major use cases include:

Use Case
Example

Interest / Behavioral Targeting = Build segments based on users' interests and past behavior so as to offer highly-valuable targeting options to advertisers

Adzerk 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 advertisers

When 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 period

John will see only one ad from Febreeze's August Flight every hour. Frequency Capping is included in all plans and does not need Business/Enterprise tiers

Excluding Ads Based on Behavior = Record what ads a user has clicked on and stop showing ads from the same Flight or Advertiser

John doesn't see another ad from Febreeze after clicking on one of their ads

Retargeting = Let advertisers retarget people who have visited their own site

Febreeze 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 campaigns

Used for user matching to increase value of the ad impression

Managing GDPR Consent = Store whether a user has given consent or not

You having a GDPR prompt and want to update UserDB that the user has said 'yes' to sharing their data

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 Adzerk if you have not included one in the request.

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

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

The UserKey is in string format and does not need to be an integer

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)

Adzerk creates: If the user field is blank in the ad request, Adzerk will generate a random GUID and send it back in the Decision API Response. You'll then need to store it.

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

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

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.

Data
Description
Example

key (string)

The unique ID associated with that user

"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 Adzerk. The values retargeting segment ID. More info here about retargeting

"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 Adzerk 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"
}

Creating/Updating a New UserDB Record

This happens in one of two ways:

  1. When Adzerk 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

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

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