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!

Overview

A flight is a collection of ads, grouped under a campaign. Most targeting and delivery rules are set at the flight level. These rules include impression goals, tracking methods, dates to run, targeting, etc.

For a full list of Flight API endpoints, click here.

Flights UI Page

You can access this in the UI by going to the drop-down box under Campaigns in the top left and clicking 'Flights', or going to the Campaigns tab and clicking on a campaign.

In the UI you can search for a flight by filtering by name, status, rate, and more.

Creating a new Flight or editing a Flight brings you to this page:

Creating/Editing a Flight

If you create more than 500 flights in a campaign, the campaign will not be able to load in UI 1.0.

With UI

  1. Enter a specific Campaign's campaign page
  2. Click 'Add a Flight to this Campaign'
  3. Put in all info and save

You can edit a Flight by clicking the pencil, and duplicate/generate ad code by clicking the three dots.

Creating With API

Please refer to our Create Flight endpoint. You can also wrap these in a flight object and send via the Create Campaigns endpoint when creating a campaign.

For required fields in the request:

CampaignId = The ID of the campaign you want to add this to. You will have gotten this in the JSON response after you created the campaign
PriorityId = What Priority you want to add flight to
Name = The name you choose to describe the flight
StartDateISO = The start date in ISO format
GoalType = What goal type you want (see here for more info)

All other fields are optional.

Example:

flight={
  "CampaignId":1234,
  "PriorityId":1325,
  "Name":"Test",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "GoalType": 1
}

Editing with API

Use the Update Flights endpoint to update Flight details.

Example request:

flight={  
    "Id":12345,
    "Name":"Fraggle Rock",
    "StartDateISO": "2015-01-01T00:00:00.0000000",
    "CampaignId":12345,
    "PriorityId":1234,
    "GoalType":2,
    "Impressions":100
}

Archiving a Flight

To keep completed flights from cluttering your campaigns page, you can either:

  • Make sure that every flight in the campaign has expired.
  • Archive the flight and/or campaign. If the flight End Date is after today, or if the flight has no End Date, you will also be able to unarchive it.

To expire a flight, set the End Date to a date later than today.

Once a campaign is expired, you can click the "Show Expired and Archived" button on the Campaigns page to view it again.

You can only unarchive flights if the flight has no End Date, or it has not yet reached its End Date.

Archiving with UI

Currently, you can only archive with Dashboard 1.0. To do that, click on a campaign and in the tools dropdown, click 'Archive Flight'.

Archiving with API

With the Update Flights endpoint, set IsArchived = true.

flight={  
    "Id":12345,
    "Name":"Flight Name",
    "StartDateISO": "2015-01-01T00:00:00.0000000",
    "CampaignId":12345,
    "PriorityId":1234,
    "GoalType":2,
    "IsArchived":true
}

You can unarchive with the Update Flights endpoint and setting IsArchived = false.

Deleting a Flight

With UI

Click on the 'X' next to the Flight in either the Campaign or Flights page. You'll get a confirmation box.

With API

With the Update Flights endpoint, set IsDeleted = true.

General Setting Fields

What
Description
API Field

Name

Friendly name of the Flight

name (string)

Categories

Used for interest targeting. More info here. Requires UserDB

Name under Category object. Requires use of Create Flight Categories endpoint

Priority

The Priority you want to give to the Flight

PriorityId
(integer)

Start Date

When you want the campaign to start. Adzerk uses GMT for start/end dates

StartDateISO
(string)

End Date

When you want the campaign to end. Only Percentage and Conversion Goal Types can be set without an End Date. Adzerk uses GMT for start/end dates

EndDateISO
(string)

Rate

These are used to estimate the revenue you've made from your advertisers. More info below

RateType
(integer)

1 = Flat
2 = CPM
3 = CPC
4 = CPA View
5 = CPA Click

Price

The amount an advertiser is paying you, based on the Rate

Price
(float/decimal)

Track Conversions

Check this to track conversions (actions post click). If you enable, there will be a box that, if clicked, will provide the conversion tracking code

IsTrackingConversions
(boolean)

Goal Type

What metric you sold the deal at to influence how Adzerk throttles the Flight in order to hit goal by end date. More info below

GoalType
(integer)

1 = Impressions
2 = Percentage
3 = Click
8 = Revenue (auction priority only)
9 = Daily Revenue (auction priority only)

Goal Amount

The number associated with the Goal Type metric for the system to aim for

Impressions
(integer)

Cap Type

Hard limits for when a flight should or should not serve. More info below

CapType
(integer)

1 = Impressions
2 = Clicks
3 = Conversions
4 = Revenue

Daily (Cap Type)

Number associated with Cap Type for a daily cap

DailyCapAmount
(integer)

Lifetime (Cap Type)

Number associated with Cap Type for a lifetime cap

LifetimeCapAmount
(integer)

Rate/Price

These are used to estimate the revenue you've made from your advertisers. These fields do not affect how often a flight is served, nor do they reflect actual payouts.

First, you select Rate, or how you are charging the advertiser:

Flat = Advertiser pays a flat rate for entire flight
CPM = Advertiser pays a fixed amount for every thousand impressions
CPC = Fixed amount per click
CPA (View) = Fixed amount for a view-through conversion (someone converts after seeing ad)
CPA (Click) = Fixed amount for a click-through conversion (someone converts after clicking ad)

Then, input Price, the amount an advertiser is paying you, based on the Rate.

A Rate of "CPC" and a Price of "$0.50" means that you get paid $0.50 for every ad click. In reporting, if you drive 1K clicks for this flight, the revenue will be reported as $500.

Rate and Price are required fields in the UI, but not in the API request when creating a Flight. If you aren't tracking revenue, simply set Rate = "CPM" and Price = "$0.00" in the UI.

Goals

In the API, the Goal Amount field is called impressions, even if it refers to percentage, click, or revenue

With Goal Type and Goal Amount, you define what metric you sold the deal at, and at what total amount. These fields also influence how Adzerk throttles the ads, so that the flight hits its goal by the end date.

For instance, if you've negotiated a 30M impression deal with an advertiser over June, you'll set Goal Type to "Impressions" and Goal Amount to "3,000,000".

Adzerk's engine will then show the ad for 30M impressions over 30 days and throttle the campaign so that it shows the ads evenly each day, or ~100K impressions a day.

The algorithm recalculates daily, so if a weekend delivers 25K impressions, the system will then shoot for more than 100K impressions/day moving forward.

For Goal Type, you can choose between:

  • impressions
  • clicks
  • conversions
  • percentage (of the priority)

If you're using an Auction priority, you can also select:

  • revenue (dollars)
  • daily revenue (dollars)

"Percentage" refers to what percent of impressions from the priority the flight should win.

For instance, say you have an advertiser who wants to take over the site. You could use the Sponsorship Priority (#1, the highest), create a flight, and set the Goal Type to "Percentage" and Goal Amount to 100%. This means the advertiser will win 100% of impressions on the site.

The maximum Goal Amount is 2147483647.

If you set up different flights targeting the same priority AND they have a combined percentage goal over 100%, Adzerk will decide a winner using a lottery based on the relative percentage goal amount.

For instance: Flight A is at 100%; Flight B is at 100%. Adzerk splits them evenly.

Percentage goals can be above 100% in order to serve flights proportionally to each other. For instance, you could set one at 100% and one at 150%. The second one will show 60% of the time (150%/250%).

If you set a percentage goal for a creative in a flight, the creative will serve that percentage of requests to the flight. If you set a percentage goal for a flight, the flight will serve that percentage of requests to the priority.

Caps

Do not set a CapType of 0 if you aren't using it. Make sure it's null

Caps may over-serve by 2% in normal traffic— this can happen due to natural traffic variations

Caps are hard limits for when a flight should or should not serve.

You set them at the Daily and/or Lifetime value and can cap by Impressions, Clicks, Conversions, or Revenue.

For instance, you have an advertiser who doesn't want more than 1M impressions a day. In which case, you set Cap Type = "Impressions" and Daily = "1,000,000".

Unlike Goals, Caps do not regulate the frequency of impressions to meet a goal over time. They are simple limits, shutting off a flight as soon as it reaches its goal.

Caps are especially useful when you want to use both Percentage Goals and Impression Caps.

For example, an advertiser may purchase a campaign that serves to 100 percent of your priority's traffic, but must not serve more than 200,000 impressions in total, or 20,000/day. In this case, you would set:

Goal Type = "Percentage"
Goal Amount = "100%"
Cap Type = "Impressions"
Lifetime = "200,000"
Daily = "20,000"

Caps can be used with or without an End Date.

For Revenue (or Budget) caps (a BETA feature), the amount is in cents. If your daily goal is $50, you'll want to put in 5000. Please note: this is the only situation in Adzerk where you should put anything in cents.

Additional Cap Behavior

When a cap is set on a flight, the ad balancer will periodically check to see how much progress has been made towards the cap. It will then project when the cap is expected to be reached. Unlike a goal, the balancer will NOT change how often an ad serves. However, the closer an ad is to meeting its cap, the more often the balancer will check. For example, in the final projected minute before an ad reaches its cap, the balancer will check the ad's status about once per second before shutting off the ad.

Because the balancer projects when a cap will be reached, unexpected traffic can skew the projection and cause the ad to overserve. Scenarios where served impressions etc. can exceed the cap are:

  • Another flight in the same priority or higher priority stops serving. This redirects impressions to the capped flight. Unless the capped flight is approaching its cap and the balancer is checking very frequently, the surge of traffic can send the flight past its cap.
  • The cap is set too low for the flight's normal traffic. In this case, it is possible for a flight to exceed its cap before the balancer checks the cap for the first time.

To prevent flights from exceeding their caps:

  • Be aware of when flights that consume large amounts of traffic stop serving, either through a scheduled end time or when they are disabled by ad ops. If necessary, add additional targeting to the capped flight so it is not overwhelmed with impressions.
  • Never set a cap that can be met in less than one hour of normal traffic.

Creatives

The Creatives tab lists the creatives/ads associated with the Flight.

Comments

An open text section for recording comments / reminders about the flight. Not available in API or Dashboard 2.0.

Targeting Fields

Our Create Flights endpoint has a deeper breakdown of the API fields for Flight targeting. Below goes into a high-level detail about the targeting options at a Flight level as available in the UI.

Behavioral Targeting

Requires UserDB, a feature on the Business and Enterprise plans.

Behavioral targeting enables two features: Interest/Behavioral Targeting and Excluding Ads Based on Behavior. Clicking these will not do anything unless you have UserDB enabled and are sending persistent IDs in the user object in the Decision API Request.

Keyword Targeting

Keyword targeting lets you serve ads to placements that contain matching keywords passed in the request. See here for more info.

With the Create Flight endpoint, you send these keywords via the keywords parameter.

Custom Targeting

Custom targeting is a powerful targeting tool that lets you target (1) custom fields you pass in the request or (2) reserved keys. Learn more here.

With the Create Flight endpoint, you send these queries via the CustomTargeting parameter.

Frequency Capping

Frequency capping stops showing ads to users based on how many ads they've already seen. Learn more here.

With the Create Flight endpoint, you send Frequency Capping using the parameters of FreqCap, FreqCapDuration, FreqCapType, and DontAffectParentFreqCap.

Site/Zone Targeting

This lets you target by Sites and/or Zones you have created.

Geo Targeting

Geo-targeting enables you to target users based on their current location. You can include or exclude locations based on Country, Region, or Metro/DMA Code (the latter for the United States only). Learn more here.

With the Create Flight endpoint, you send these properties via the geotargeting object.

Day Parting

Hour / day parting lets you show ads only during certain hours of the day, or certain days of the week. Learn more here.

Distribution

Distribution is a way of determining ad delivery within a flight. Learn more here.