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!

Getting Started Guide

Initial Reading

Here are some overviews about our taxonomy and terminology:

How Adzerk Works
Adzerk Glossary
Intro to Ad Tech
Ad Decision Engine Overview
Campaigns Overview
Inventory Overview

Second, we recommend doing some test pings on the APIs with our quickstart guides:

Decision API Quickstart
Decision API (Advanced)
Management API Tutorial
UserDB Tutorial (Interests)

Understanding Inventory

Inventory is the Adzerk term for what properties (sites/apps) the ad will appear on. Most of these are pre-created for you.

Understanding Campaign Hierarchy

Campaign refers to information about who is advertising, what their targeting is, and what the ad looks like. It consists of four "levels": Advertisers --> Campaigns --> Flights --> Ads.

Building The Ad Unit

Before showing an ad, you'll have to configure your Custom Ad Unit. This can be done with the UI or API.

Additionally, you could use our Beta Creative Templates option. Speak to your Adzerk rep to learn more.

Some additional information about ads are:

Creatives General Settings
Ad General Settings
Create Creative
Create Ads
Ad Sizes / Types

In Adzerk terminology, 'creative' refers to information about what's being shown, such as the image, the source URL, and metadata. 'Ad' refers to a creative that's tied to a Flight and now eligible to serve (targeting is thus tied to an 'ad' not a 'creative'). We break it down because you could have the same 'creative' across multiple Flights.

Understanding Priorities

Priorities are the business rules for determining what ads have precedence over others. For instance, see the below chart:

The default priorities are:

Priority Name
Priority Number

Sponsorship

1

Premium

5

Networks

10

House

20

1 is the highest priority; 100 is the lowest. You can add up to 96 more beyond the defaults.

Some ideas around how to structure priorities are:

Scenario
Advice

You want to sell every available impression to an advertiser

Use default "Sponsorship" (#1) for that Advertiser's Flight

You want all advertisers to bid on each ad slot

Use default "Premium" (#5) for all those advertisers. They are all equally eligible

You want to have high-CPM advertisers eligible for slots, but if those aren't all filled, you'll open it up to lower CPM advertisers

Use default "Premium" (#5) for high CPMs. Create a new Priority (say, "Remnant"), with Priority of 8, for the low CPMs

You want to show house ads if there are no advertisers for a given ad slot

Use default "House" (#20), alongside higher Priorities

Understanding Business Logic

With Adzerk, you can sell, pace, and cap by any metric, including:

Metric
Examples

Flat rate (fixed amount)

$100K over 30 days

CPM
(cost per thousand impressions)

$5.00 CPMs for 100K impressions

CPC
(cost per click)

$1.00 CPC for 10K clicks

CPA
(cost per action)

$20 CPA for 500 actions. Here, "actions' can be whatever event you want

Additionally, you can optimize revenue through bidding strategies:

How Winner Is Selected
Example
Use Cases

Lottery (random selection of eligible ads)

Both Dunkin Donuts and Starbucks are eligible to show an ad. The Ad Decision Engine picks DD randomly

If you're focused on guaranteeing a certain number of imps, clicks, spend, etc

Auctions (highest bidder wins)

Both DD (with a $20 CPM bid) and Starbucks (with a $10 CPM) are eligible to appear. DD is picked because it has higher bid and pays $20

If you want to maximize revenue. However, since every ad is an auction, it's hard to guarantee to the advertiser how many impressions/clicks they'll see

2nd Price Auctions (highest bidder wins, pays $0.01 more than 2nd highest bidder)

Both DD (with a $20 CPM bid) and Starbucks (with a $10 CPM) are eligible to appear. DD is picked and pays $10.01

This helps to maximize revenue while selling the ad at "true market value". Advertisers generally pay less, but it also provides better performance to the advertiser, increasing stickiness

DD and Starbucks have the same bid, but Starbucks's relevancy score is higher and is selected

If you'd like to incorporate a relevance metric (that you create and send) for the Ad Decision Engine. Useful for identifying ads users may not like

You set up these rules by a combination of Priorities / Waterfall and Flights. Refer to our documents for more details.

Tracking Custom Events

Adzerk enables you to track impressions, clicks, actions, and any custom metric. For the latter, you request custom event URLs and then ping Adzerk server-side when they happen (or add the pixel endpoint to the page).

For each Event ID you request, you'll receive separate URLs to hit.

Targeting Options

Robust targeting is how you can justify higher ad rates and offer better ad experiences to your users.

A list of the more relevant targeting options are:

Geo-Targeting
Day & Hour Parting
Custom Targeting
Frequency Capping
User-Level Targeting
Keyword Targeting
Search Term Targeting
Category Targeting

UserDB Targeting

UserDB requires the Business or Enterprise tier.

One of the most powerful tools available to you is UserDB, your 1st party Data Management Platform.

For information on UserDB, you can visit:

UserDB
UserDB Tutorial (Interests)
User-Level Targeting

UserDB requires the use of a "UserKey" (or persistent identifier) that's sent in every Decision API request. This UserKey is saved in UserDB, alongside the information we have about that user. When that UserKey comes through the request, Adzerk checks UserDB to see what info is tied to them.

The most common methods of generating this ID is:

Persistent Identifier

Log-In Username

Mobile Identifiers (iOS IDFA; Android GAID)

Internal proprietary identifier

Interest Targeting

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

Type
Explanation

Sport Lovers

People who have engaged with sports content (either organic content 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:

When

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.

You'll want to store this data as Interests in UserDB. Please refer here for info on how to ping the endpoint to upload the correct Key/Value pair.

Then, to target these users, refer to our Custom Targeting and UserDB Reserved Keys docs. You'll use a query like below when setting up Flights.

UserDB Interest Category
Example Custom Targeting Query

Fast Food Lovers

$user.interests contains "Fast Food"

Affluent Customers

$user.interests contains "Affluent"

Demographic Targeting

Demographic targeting refers to targeting users based on user-given key/value pair information, like:

Key
Value

Gender

Male, Female

Age

18+, 20, 40-50, etc

Income

<$50K, $50K - $100K, $100K+

You'll want to store this data as a Custom Property in UserDB. Please refer here for info on how to ping the endpoint to upload the correct Key/Value pair.

Then, to target these users, refer to our Custom Targeting and UserDB Reserved Keys docs. You'll use a query like below when setting up Flights.

UserDB Custom Property Key/Value
Example Custom Targeting Query

Age: 30

$user.custom.age > 25

Gender: Female

$user.custom.gender = "Female"

Please note: Adzerk is not providing demographic data. You need to be collecting that and sending it to UserDB. Adzerk will do the heavy lifting of using that data to determine if an ad is eligible to be shown.

What to Send in Decision API Request (For Beginners)

Below looks at the most important fields to pass in the Decision API Request. Refer here for a full list of all parameters and example JSON requests.

Arguments

Property
Description

placements
(object)

Describes more details about the placement (ad slot). Required

user
(object)

The UserKey for UserDB

time
(string)

The UNIX epoch timestamp. For time-of-day targeting

ip
(string)

IP Address. For location targeting

keywords
(array)

Keywords for Keyword Targeting

Placement Arguments

Property
Description

divName
(string)

A unique name for the placement defined by you. Required

networkId
(integer)

Your numeric network id. Required

siteId
(integer)

The numeric site id. The "site" will likely be Web, iOS, or Android. Required

adTypes
(array)

The adType id for your native ad unit. Required

eventIds
(array)

Requests a URL for a special event. See here for more info

properties
(object)

A hash of key/value pairs used for Custom Targeting

To get networkId: sign into the UI; your network ID is in the URL: http://chris.adzerk.com/network/9999/dashboard (9999 is the ID)

To get siteId: in UI, go to Inventory --> Sites --> Click on right Site: your Site ID will be in the URL: http://chris.adzerk.com/publisher/41380/site/767400/zcode (767400 is the ID)

To get the adTypes id, you have a few options:

  1. If it's a pre-created ad type, it's listed here
  2. If you create with the Ad Types API, it's in the response as id
  3. You can ping the List Ad Types API API to get it
  4. You can also go to UI --> Inventory --> Sites --> Click on Site Name --> Under the "Size" dropdown, select the custom size. In the Step 2 box, you'll see code. Find the string that looks like this: ados_add_placement(94, 727490, "azk71247", 24). The ID is the last number (24 here)

Most Relevant Parameters in Decision API Response

The Decision API Response will return many fields, some more relevant than others. Below looks at the more salient fields:

Property
Notes

imageURL

The URL of the hosted Adzerk image

clickURL

URL for the click event, which could be an outside link, an "expand the profile" click, etc. You don't need it if you don't want

impressionURL

URL to record impressions. Needs to be called via browser or pinged server-side

customData

This is the metadata field. Use this if there's additional info tied to the ad you want to insert into your CMS

events

The URLs for any custom events you requested, broken down by id. Can be pinged server-side

You'll want to parse this information and insert it into your CMS to create a fully integrated native ad.

Parsing Metadata

When setting up an ad, you can also insert data (in JSON format) into the metadata field.

Anything you put here will be returned in the Decision API JSON response. So, when you get the API Response, you can parse this field and insert the information into the ad. Examples include call-to-action, location information, any custom text, etc.

{
  "headline": "Test Headline",
  "cta": "Download Here"
  }

Using Management APIs

While you can build your own ad server with a combination of the Decision API and the Adzerk UI, many clients like using the Management APIs to automate the creation/updating/deleting of Campaigns, Flights, Ads, Priorities, and more.

This is especially useful if you are building a self-serve dashboard for internal users or external advertisers.

For next steps, try the Management API Tutorial. Some additional reading material include:

  1. Campaign API Overview
  2. Inventory API Overview
  3. User Management API Overview

Using Reporting API

The Adzerk Reporting API offers multiple ways to pull data into your system, including scheduled reports and real-time data.

Getting Started Guide