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!

Interest/Behavioral Targeting

Interest / Behavioral Targeting requires UserDB, a feature in the Business and Enterprise plans.

Interest Segments are loved by advertisers, who will pay more knowing that they are showing ads to a targeted audience. They can also be used by you on the backend to optimize ad placement and maximize CTRs/CRs.

Overview

With Interest Targeting, you could let Advertisers target specific interest-based segments (and charge a premium for doing so). Such as:

Segment
Description

Sport Lovers

People who have engaged with sports content (either organic or paid ad)

Affluent Customers

People whose behavior indicates high income bracket (searches for expensive homes, etc)

Any custom segment you can build based on either user-given or behavior-based info

This data can be tied to a user in multiple ways:

Method

Using behavioral ad tracking, Adzerk adds users to Interest Categories based on ads they interact with. Learn more here.

Pinging UserDB directly. Learn more here.

To help with terminology on this page:
`Flight Categories' or categories = the interests you want to target
interest = the parameter that 'categories' are saved as in UserDB, which is associated with the persistent UserKey
$user.interests CONTAINS "basketball" = the Reserved Keys Custom Targeting format used when creating Flights/Ads with the Create Flight or Create Ads endpoints, or the UI.

A user's record can collect up to 100 interests

UserDB UserKeys

Adzerk saves a user's interests in UserDB, a data management platform for storing user-level data (more info here). All data is tied to a UserKey, which is the persistent key field in UserDB, and is located in the interests field in UserDB.

Setting Up Behavioral Tracking - API

Many clients create Interest Segments by tying an Interest to a specific Flight and then, when a user clicks/converts on an Ad from that Flight, automatically updating the user's UserDB record to indicate he/she should be in that segment.

For instance, if you are showing ads for the NBA, if a user clicks on those ads, that user could be added to the "Sports Fan" interest category.

To do this, you need to first Create a Flight with Interest Tracking enabled and THEN map an Interest to it (using the Flight's ID from the Create Flight Response).

You do not have to enable behavioral tracking to create Interests. Instead, you could ping UserDB directly and add an Interest to a UserKey.

1. Create a Flight And Enable Tracking

You'll use the BehavioralTargeting object in the Create Flight or Update Flight endpoint to enable Interest Tracking.

Within that are two other objects: onClick and onConvert. These refer to whether you want to add an Interest to a user based on whether they clicked on the ad, or both clicked AND converted (ex: made a purchase).

Then, you'll want to mark the boolean field of storeCategoriesFromFlightAsInterest as true for onClick or onConvert.

For example, here's enabling it on click:

flight={
  "Name":"Nike Christmas Flight - iPhones",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "EndDateISO":"2017-12-31T00:00:00.00.0000000",
  "CampaignId":1234,
  "PriorityId":1234,
  "GoalType": 1,
  "BehavioralTargeting": {
    "onClick": {
      "storeCategoriesFromFlightAsInterest": true
    }
  }
}

Here's enabling it on Conversion:

flight={
  "Name":"Nike Christmas Flight - iPhones",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "EndDateISO":"2017-12-31T00:00:00.00.0000000",
  "CampaignId":1234,
  "PriorityId":1234,
  "GoalType": 1,
  "BehavioralTargeting": {
    "onConvert": {
      "storeCategoriesFromFlightAsInterest": true
    }
  }
}

2. Create and Map an Interest to a Flight

Once the Flight is created, store the id in the Response. This is the Flight's ID.

Then, you'll use the Create Flight Categories endpoint to add an Interest to the Flight. If the Interest isn't already created in Adzerk, it will create it.

You'll need to post the name property wrapped in a category object, like:

category={
  "Id":123456,
  "Name":"Sports"
}

id here is the Flight's ID. Pinging this endpoint will add the Interest to the Flight.

Setting Up Behavioral Tracking - UI

1. Adding Interests to Flight

  1. Navigate to the 'General Settings` in the Flight
  2. Under Categories, add in the Interests. When you add a category, the Interest is automatically created in the system
  3. Save

2. Enabling Interest Tracking

  1. In the Flight's Settings, click on Behavioral Targeting on the settings on the left
  2. Choose Clicks or Converts under "Store this flight's categories as an interest for a user when that user clicks or converts on an ad from this flight"

Note: checking clicks AND converts is the same thing as just clicking clicks

Categories can have up to 10 characters

Pinging UserDB Directly with Interest

You also have the option to attach an Interest to a UserKey directly, by GETting a pixel URL as an endpoint.

URL Format

http://e-{networkId}.adzerk.net/udb/{networkId}/interest/i.gif?userKey={userKey}&interest=xxxxxxxxx

Example

http://e-{networkId}.adzerk.net/udb/8601/interest/i.gif?userKey=435645243&interest=basketball

Example with Multiple

http://e-{networkId}.adzerk.net/udb/{networkId}/interest/i.gif?userKey=435645243&interest=basketball,soccer

Once you ping this URL endpoint, UserDB will update the UserKey's record to indicate he/she should be in the Interest Segment.

UserKey in the string refers to the key value you'd normally send in the user object of the Decision API request.

For this to work, you must have already create the Interest in the system with the Flight Categories endpoint.

Viewing Interest Categories

You can pull Interest Categories either by Flight or Network with these Campaign Management API endpoints:

List Flight Categories
List Network Categories

Creating a Flight Targeting an Interest Segment

An Interest Segment refers to all the users who are now associated with a specific Interest, either through behavioral click tracking or directly updating UserDB.

You can target this segment with either the UI or API. It requires the use of Custom Targeting, Reserved Keys, and Zerkel Queries.

UserDB Interest Category
Example Custom Targeting Query

Sport Lovers

$user.interests contains "Sport Lovers"

Affluent Customers

$user.interests contains "Affluent"

Here's an example Create Flight API request to set-up a Flight targeting the "Sport Lovers" interest:

flight={
  "CampaignId":1234,
  "PriorityId":1325,
  "Name":"Adidas - New Basketball Shoes",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "GoalType": 1,
  "CustomTargeting":"$user.interests CONTAINS \"Sports Lovers\""
}

Make sure to use \ before quotation marks in strings to avoid the API request breaking

In this example, Adzerk's Ad Decision Engine will show an Ad from this Flight ONLY if the user's UserDB record shows them tied to the "Sports" interest.

Remember: for interest targeting to work, you will need to pass the UserKey in the user object's key field of the Decision API request. If you send the UserKey, Adzerk's Ad Decision Engine will cross-reference with UserDB when picking the right ad. If you do not send UserKeys, interest targeting will not work.

Reporting on Interests

Adzerk's reporting does not break down custom targeting. However, you could create Flights that target just one category, which will let you see the performance that way.

Retargeting

An additional way to use behavioral tracking to create Segments is through our Retargeting capability. With this, you can use the Retargeting Endpoint to directly ping UserDB and add an UserKey to a retargeting segment.

You can have an unlimited number of Retargeting Segments, and these could be set-up like:

Retargeting Segment #1 = Homepage
Retargeting Segment #2 = Rug Product Page

(Alternatively, you could create Interest Categories of "Homepage", "Rugs", etc).

To do this, you'll:

  1. Make sure you have created yourself as an Advertiser in Adzerk's system

  2. GET this Retargeting Endpoint pixel: `http://e-{networkId}.adzerk.net/udb/{networkId}/rt/{advertiserID}/{segment}/i.gif AND make sure to have "azk=<USERKEY>" at the front (see cURL example).

curl -b "azk=235342" http://e-1234.adzerk.net/udb/1234/rt/113959/42/i.gif

The pixel template is: http://e-{networkId}.adzerk.net/udb/{networkId}/rt/{advertiserID}/{segment}/i.gif.

The URL is composed of three sections you'll need to fill out:

Property
Description

NetworkID
(integer)

This is your Network ID

AdvertiserID
(integer)

This is your Advertiser ID

Segment
(integer)

This is an integer you choose to denote the Retargeting segment. You could have multiple if you wanted to track multiple pages

  1. When you create a Flight/Ad in the UI or Create Flight/Create Ads endpoints, you'll want to use Reserved Keys to build a segment around $user.retargetingSegments.

In the query, the string should look like this: $user.retargetingSegments.b42 = 1.

Here, b42 refers to the Advertiser ID. If your Advertiser's ID is "676", it would be $user.retargetingSegments.b676. "1" is the code of the retargeting segment.

For instance:

flight={
  "CampaignId":1234,
  "PriorityId":1325,
  "Name":"Retargeting - Homepage",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "GoalType": 1,
  "CustomTargeting":"$user.retargetingSegments.b42 = 1"
}

If you use the UserDB Read User Endpoint, you can pull and filter the resulting data by the retargetingSegments field to see all the Retargeting Segments you have created (however, it only shows the integer, not what it refers to. For instance, it'll show Segment "1" is tied to a user...but not that "1 = homepage")

Interest/Behavioral Targeting