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!

Ad Pacing (Goals)

Overview

Ad pacing - or goals - refers to the automatic balancing of impressions for a Flight or Ad so that the campaign hits a desired metric over the course of its lifetime.

For instance, if you've negotiated a 30M impression deal with an advertiser over June, Adzerk's Ad Decision Engine will show the ad for 30M impressions over 30 days and throttle the campaign so that it shows the ads evenly each day, or ~1M impressions a day.

This is an automated, constantly-updating feature that helps ensure your advertisers hit their goals.

Ad Goals are different from Ad Caps. You use Ad Goals to pace ads evenly over time. It involves complex logic and intra-day adjustments. Ad Caps, on the other hand, don't use logic. They'll just turn off an ad if it hits the cap.

What You Can Pace Against

You set Goals at the Flight level. For more information on how to set them, click here.

For Goal Type, you can choose between Impressions, Clicks, Conversions, and Percentage.

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

Flights set to auction bidding can also pace by Daily Revenue and Lifetime Revenue.

Budget Goals

Budget/Revenue Goals are currently in BETA. It works just for Flights that use an auction priority.

Budget goals are a goal type that balances the impressions a flight or ad serves so that it earns a specific amount of revenue either by its End Date or per day.

There are two types of budget goals:

  • Lifetime budget goals: Sets the amount of revenue a flight or ad should earn before its End Date. (Note that an End Date is required to use lifetime goals.)

  • Daily budget goals: Sets the amount of revenue a flight or ad should earn per one UTC day. A daily budget goal resets at midnight UTC.

Setting Up Budget Goals - API

On the Flight Level

When Creating a Flight with the Create Flight endpoint, make sure to:

  1. Set GoalType to 8 or 9. 8 = Lifetime Revenue and 9 = Daily Revenue
  2. Set Impressions to the target budget

While the field is called impressions, it's the correct field to use for budget goal amounts.

On the Ad Level

When Creating/Editing an Ad with the Create Ads endpoint, make sure to:

  1. Set GoalType to 8 or 9. 8 = Lifetime Revenue and 9 = Daily Revenue
  2. Set Goal to the target budget

Setting Up Budget Goals - UI

On the Flight Level:

  1. Create a new Flight
  2. Select an Auction priority for a flight
  3. In the Goal Type dropdown, choose either "Revenue" or "Daily Revenue"
  4. In the Goal field, enter the budget goal (in dollars)
  5. Save

On the Ad Level:

  1. Add a New Creative/Ad
  2. In the Distribution dropdown under "Delivery Settings", select "Override"
  3. In the Goal Type dropdown, choose either "Revenue" or "Daily Revenue"
  4. In the Goal field, enter the budget goal (in dollars)
  5. Save

Budget Goal Behavior Overview

Unlike budget caps, budget goals will pace how often an ad or flight serves, responding to changes in inventory by raising or lowering the weight of the ads (which determines how often an ad can serve).

Lifetime budget goals set a weight so an ad serves evenly over the course of its lifetime.

Daily budget goals calculate a weight over 30 days of traffic to determine an appropriate daily weight.

When used with an auction priority, budget goals create an AdWords-like bidding system for your inventory.

Budget Goal Behavior Explained In-Depth

This is a detailed description of how budget goal weights are calculated in Adzerk. As a deep dive into the ad selection process, this document is useful for understanding the design of budget goals and for troubleshooting delivery issues at an advanced level.

Budget goals add capabilities to the ad server engines to support optimal
allocation of inventory in auction priorities. Optimal allocation includes the
following:

  1. Ads can have goals — inventory is allocated to the ad over time
    time between its start and end dates such that revenue is generated as
    smoothly and evenly as possible with the ad reaching its goal amount just as
    it reaches its end date.
  2. When supply exceeds demand, all demand is filled — ads will not
    compete for impressions (and consequently will be priced at the floor price)
    when there are more than enough impressions available to fill the demand.
  3. Competition between ads in auctions ramps up smoothly when demand exceeds
    supply
    — competition only occurs when multiple ads want the same
    impression at the same time to meet their goal. This generally means that
    the pacing needs of the ads will determine how often they compete against
    each other in auctions.

Balancing and Pacing

Goals provide a mechanism by which the rate at which ads serve is continually
regulated and adjusted in order to achieve some set number of impressions,
clicks, conversions, and now revenue over the lifetime of the ad. The optimal
rate is such that the ad serves as evenly as possible over time, taking into
account variations in inventory, CTR, effective CPM, and other considerations.

Two concepts work together to regulate the rate at which an ad will serve:

  • pacing — Engines employ probabilistic methods to regulate the rate
    at which ads will serve relative to each other within the constraints of the
    targeting rules and available inventory. The system is designed such that
    each ad is associated with a weighting parameter and the probability that an
    ad will serve for any individual request is proportional to its weight.
  • balancing — Both real-time and historical performance of ads is
    continuously monitored. This information is used to adjust the ad weightings
    while the ads are serving so they maintain the optimal rates to achieve their
    goals.

Note that pacing is essentially a rate-limiting function. Since engines can not
serve more impressions than the available inventory allows, the only way it can
regulate the pace is by limiting how fast ads serve. Dynamic behavior is the
result of feedback in the balancing/pacing loop.

For example:

  • Consider a priority with three ads, A, B, and C.
  • Suppose A starts to fall behind — it needs to serve impressions faster
    to achieve its goal.
  • The balancer is monitoring A's (and all the other ads) performance, and it
    decides to increase A's weighting so it can serve at a faster rate to catch
    up.
  • The engines need to allocate inventory to A, B, and C, in ratios
    proportional to their weights. Since A's weight was bumped up it will serve
    faster (and B and C will serve more slowly).
  • After a while one of two things usually happens: either A begins to overshoot
    its goal or one (or both) of the other ads will begin to fall behind. In the
    first case A's weight is reduced and in the second case the other ad's weight
    is increased.
  • This, in turn, causes A to serve more slowly, and the cycle repeats.

Lotteries

Lotteries are an important part of the probabilistic model the engines use to
set the rate at which ads serve. In combination with the balancing weights they
are an effective tool for portioning out available inventory to multiple ads in
a priority such that each ad gets a fair proportion of the available impressions.

The simplest case is the "Lottery Priority", where each ad in the priority gets
some percentage of the total available inventory, proportional to its weight.
In this type of lottery only a single ad "wins"; ads do not compete in auctions
against each other.

The lottery priority is conceptually simple: each ad is assigned a number of
lottery balls, according to its weighting. When all ads have been assigned the
correct number of balls the balls are thrown into a sack, and a random ball is
selected. Whichever ad was assigned that ball wins the lottery.

A: weight = 3
B: weight = 4
C: weight = 5

Total number of balls: 3 + 4 + 5 = 12

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | A | A | A | B | B | B | B | C | C | C | C | C |
         +---+---+---+---+---+---+---+---+---+---+---+---+
                                       |
+--------------------------------------+
|
X = a random number between 1 and 12 (say 8). C is the winner!

It is easy to see that the probability that a given ad will serve is proportional
to its weight, and since the winner is chosen randomly all ads in the lottery
will get their share of inventory over time.

However, the above example is slightly misleading, because it would imply that
a lottery priority will always select a winner, which would be problematic in
situations where inventory exceeds demand — ads would overshoot their
goals. To address this issue there is a maximum or reference weighting against
which individual ad weightings are scaled.

So in the situation where supply is greater than demand:

A: weight = 1
B: weight = 2
C: weight = 3

Max Wt. = total number of balls = 12

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | A | B | B | C | C | C |   |   |   |   |   |   |
         +---+---+---+---+---+---+---+---+---+---+---+---+
                                       |
+--------------------------------------+
|
X = a random number between 1 and 12 (say 8). There is no winner!

And, conversely, when demand is greater than supply:

A: weight =  4
B: weight =  8
C: weight = 12

Max Wt. = total number of balls = 12

Scaling factor = number of balls / sum of weights = 12 / 24 = 1/2

A: scaled weight =  4 / 2 = 2
B: scaled weight =  8 / 2 = 4
C: scaled weight = 12 / 2 = 6

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | A | A | B | B | B | B | C | C | C | C | C | C |
         +---+---+---+---+---+---+---+---+---+---+---+---+
                                       |
+--------------------------------------+
|
X = a random number between 1 and 12 (say 8). C is the winner!

This scaling behavior suggests an interpretation of the ad weightings: weights
are between zero and max weight, and weight / max weight is the proportional
to the probability that the ad will serve for a given impression.

In the previous example A's weight of 4 implies that it wants 1/3 of all
available inventory, B's weight of 8 corresponds to 2/3, and C's weight
of 12 corresponds to all available inventory. Since there is a maximum of
100% to distribute among the three ads in the priority we scale them down
proportionally, so they each get their fair share of the limited number of
available impressions.

Paced and Balanced Auctions

In the example above only a single ad may win a given lottery drawing, even if
demand exceeds supply. Paced auctions require multiple ads to compete for
inventory in this case, but still retain the ability to accurately pace ads so
they achieve their goals optimally.

This is accomplished by adding a modified lottery drawing before the auction
takes place. The objective of this pre-auction lottery is to select the ads
that will be allowed to bid in the auction. Then the auction determines which
ad wins the impression.

The concepts of weighting and max weight are carried over to this new type
of lottery, but when demand is greater than the available inventory the weights
are not scaled down as they were in the above example. Instead, a series of
lotteries are conducted, with a possible winner for each one. The rules of the
lottery are designed such that there is at least one winner across all of the
lotteries whenever demand meets or exceeds supply.

Since the mechanics of the modified lottery are the same as the simple lottery
when supply meets or exceeds demand, consider the last example above, where the
demand is 2x supply (that is to say, the ads require twice as many impressions
per second to reach their pacing goals than are currently available in their
priority):

A: weight =  4
B: weight =  8
C: weight = 12

First, the ads are shuffled to obtain a random ordering, say B, C, A, and
each ad is assigned lottery balls according to its weight. So A gets 4 balls,
B gets 8, and so on. The first lottery is constructed by loading balls from
each ad into available slots in order, and a winner is selected:

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | B | B | B | B | B | B | B | B | C | C | C | C | All of C's balls
         +---+---+---+---+---+---+---+---+---+---+---+---+ don't fit!
                   |
+------------------+
|
X = a random number between 1 and 12 (say 3). B is the winner!

So B won the first lottery, and C lost. But C only got to play 4 of the
12 balls it was assigned! In this case we allow C to play its remaining balls
in the next lottery.

However, allowing C to play in two lotteries changes the odds. It turns out
that splitting C's balls between two lotteries yields a slightly lower
probability that C will win a lottery than if it were able to play all of
its balls in a single lottery. To correct this we add an adjustment — the
number of balls C can play in the next lottery is prorated such that the
total probability is preserved.

The prorated probability for the second lottery is given by:

y = (p - x) / (1 - x)

where y is the prorated probability, x was the probability of winning the
first lottery, and p is the original probability corresponding to the ad's
weight.

A second lottery is now constructed, with C's remaining balls (plus the adjustment
which works out to 4 extra balls, for a total of 12), and as many of A's balls
as there are available slots:

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | C | C | C | C | C | C | C | C | C | C | C | C | No slots left for A!
         +---+---+---+---+---+---+---+---+---+---+---+---+
                                           |
+------------------------------------------+
|
X = a random number between 1 and 12 (say 9). C is the winner!

So C won this lottery, but again, A didn't get to play, so a third
lottery is constructed. In this lottery A plays its 4 balls:

Lottery:   1   2   3   4   5   6   7   8   9  10  11  12
         +---+---+---+---+---+---+---+---+---+---+---+---+
         | A | A | A | A |   |   |   |   |   |   |   |   |
         +---+---+---+---+---+---+---+---+---+---+---+---+
                           |
+--------------------------+
|
X = a random number between 1 and 12 (say 5). There is no winner!

Now there are no more balls to play, so the lottery series is complete. The
winners, B and C, move on to the auction phase, where they must bid against
each other to win the impression, and the winner will pay the second-price
amount.

What to Expect

First of all, keep in mind that balancing is a continuous process, so ad
weights will be updating frequently to ensure that ads continue to serve at
their optimal rates through the ebb and flow of inventory and demand levels.

To get a feel for how paced and balanced auctions will behave, consider the
range of possible outcomes in the previous example. In the example, B and C
were ultimately chosen, but it could have been A and C, or A, B, and C
if the lotteries had gone a different way.

  • Why is C a winner in every outcome? C always makes it through the
    lottery selection process because it has the maximum weight; it wants every
    available impression. Thus, it is sure to win one of the lotteries in the
    series, and consequently always places a bid in every auction.
  • How likely is it for C to bid against A, and/or B? Since A's
    weight is 4, we expect it to win one lottery in the series about 4/12, or 33%
    of the time. Likewise, since B's weight is 8, we expect it to win a lottery
    about 8/12 or 66% of the time. Whenever A and/or B can win one of the
    lotteries in the series they may place a bid in the auction.
  • Why does C sometimes bid against A, sometimes against B and sometimes
    both A and B?
    It works out this way because both A and B want some
    inventory, and since C wants it all they must bid against C in the auction
    to get their share. You can expect auctions with two ads to occur more often
    than auctions with all three ads.
  • What range of effective CPM do we expect? The different ads in the auctions
    determine the eCPM of the winner if the priority uses second-pricing rules. So
    if C bids $1.00 CPM, B bids $0.75, and A bids $0.50, for example, C
    might end up with an effective CPM in the neighborhood of $0.68 or so, because
    it will win every auction at either $0.76 or $0.51 CPM, depending on whether
    it's bidding against A or B.