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 Tutorial (Interests)

UserDB is a feature in the Business and Enterprise plans. Please ask your Account Manager (or email support@adzerk.com) to turn it on.

Overview

UserDB is your turnkey data management platform. 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:

Hashed log-in username

For mobile apps, you can pull and send the IDFA (iOS) or GAID (Android)

Proprietary ID stored in a cookie

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

Set up with UI

  1. Edit the "Test Flight" Flight from the Quickstart
  2. Go to the Categories box in General Settings
  3. Put in 'shoes' and press enter
  1. Go to the Behavioral Targeting section
  2. 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
  3. Save flight

Click on the Ad

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

  2. 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

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

  4. 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"}}' http://e-<networkId>.adzerk.net/api/v2
  1. 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, Adzerk 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 Adzerk 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"}}' http://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.

UserDB Tutorial (Interests)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.