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!

Relevancy Score

BETA

Relevancy Score is in Beta. These docs are subject to change. If you have additional questions, please ask your account manager.

With Adzerk's Relevancy Score functionality, you set the Relevancy Score at the Flight or Ad level. Adzerk then uses this number to calculate an Ad Rank, which is used by the Ad Decision Engine to pick ads. Adzerk is not actually calculating the Relevancy Score itself (that must be passed by you via the API).

What is a relevancy score?

Relevancy score is an ad or flight-level setting that can be used to influence ad selection in an auction. An ad with a higher relevancy score will win an auction over similarly priced ads.

For example, say you’ve built a self-serve advertising system on top of Adzerk where bidders compete in an auction. Some bidders may bid a high CPM for impressions, but their ads are not relevant to the inventory, or they are poor quality, or they otherwise do not perform well.

By assigning a relevancy score, you can choose how to reward ads that are on-message and popular with viewers while requiring irrelevant ads to pay more to be eligible to serve.

In Adzerk, relevancy scores are integers between 1 and 1000. The lower the relevancy score, the lower the ad will be ranked in the auction.

Setting relevancy scores

You can set relevancy scores:

  • On a flight
  • On an ad
  • As part of a request by overriding the settings for flights and/or ads

You can set relevancy scores using programmatic metrics or using custom metrics. Currently, we only support custom metrics.

Note

An ad in a relevancy score-enabled priority that does not have a relevancy score set on the flight or ad will have a default relevancy score of 500.

Enabling an auction priority for relevancy scores

Before you can set a relevancy score, you must first enable your auction priority for relevancy scores. To do this, create a new priority or update a priority via the API to include the following object:

 "RelevancyScoreConfig":{  
      "components":{  
         "custom":1
      },
      "aggregation":2
   }
Name
Type
Required
Description

components

object

Y

Sets the metric(s) used for calculating relevancy scores. Currently only one metric is available, custom. Its value is an enum that sets the aggregator for the component.

aggregation

int

Y

Sets the how multiple components should be aggregated into a single relevancy score. Not yet available, so set it to an integer between 1 and 5.

Aggregators

Each component uses an aggregator to compute a relevancy score when scores have been set for both a flight and its ad. Set the aggregator as an enum.

Enum
Description

1

Use the minimum score.

2

Use the maximum score.

3

Use the mean of the scores.

4

Use the least specific score. For example, choose the flight score instead of the ad score.

5

Use the most specific score. For example, choose the ad score instead of the flight score.

curl -X POST -H "X-Adzerk-ApiKey:<API-KEY>" https://api.adzerk.net/v1/priority -d 'priority={"Name":"Relevancy Score Priority","ChannelId":12345,"Weight":5,"IsDeleted":"false","SelectionAlgorithm":1,"RelevancyScoreConfig": {"components": {"custom": 1 }, "aggregation": 2}}'

Setting relevancy score on a flight

To set a relevancy score on a flight using the custom component, add the parameter CustomRelevancyScore to the flight object. This can be used for both creating and updating flights.

Name
Type
Required
Description

CustomRelevancyScore

int

N

Sets the relevancy score. Must be between 1 and 1000.

curl -X POST -H "X-Adzerk-ApiKey:<API-KEY>" https://api.adzerk.net/v1/flight -d 'flight={"Name":"Relevancy Score","StartDate":"1/1/2015","CampaignId":123456,"PriorityId":123456,"GoalType":2,"IsActive":true,"Price":1,"Impressions":100,"RateType":2,"NoEndDate":true,"IsUnlimited":false,"CustomRelevancyScore":500}'

Setting relevancy score on a ad

To set a relevancy score on a ad using the custom component, add the parameter CustomRelevancyScore to the ad object. This can be used for both creating and updating ads.

Name
Type
Required
Description

CustomRelevancyScore

int

N

Sets the relevancy score. Must be between 1 and 1000.

curl -X POST -H "X-Adzerk-ApiKey:<APIKEY>" https://api.adzerk.net/v1/flight/12345/creative -d 'creative={"CampaignId":12345,"Creative":{"Id":123456},"FlightId":12345,"IsActive":true,"CustomRelevancyScore":500}'

Relevancy Score Overrides

You can override the relevancy score for ads, flights, or both using the Overrides feature. When a relevancy score is overridden, the aggregators set on the priority will no longer apply.

Ados.js request

To override the relevancy score in an ados.js request:

  1. Add the .setOverrides method to theados_add_Placement(); function
  2. Create an object for the flights or ads you are overriding
  3. Set the relevancyScore for each ID.

For example:

ados_addPlacement(...).setOverrides({"ads": {"123456": {"relevancyScore": 333}}})
ados_addPlacement(...).setOverrides({"ads":{"123456":{"relevancyScore":180}},"flights":{"123456":{"relevancyScore":715}}})

Decision API request

To override the relevancy score in a Decision API request, create an overrides object as a parameter in the placement object.

For example:

"overrides": {
   "ads": {
      "123456": {
         "relevancyScore": 333
      }
   }
 }
"overrides": {
   "ads": {
      "123456": {
         "relevancyScore": 180
      }
   }
   "flights": {
       "123456": {
         "relevancyScore": 715
      }
   }
 }

Relevancy Score and Revenue

Unlike other auction priorities, priorities enabled for relevancy score will choose the ad with the highest ad rank:

AdRank = Bid * RelevancyScore

First price auctions

In a first price auction, impressions chosen using relevancy score will record the full price of the ad.

Second price auctions

In a second price auction, impressions chosen using relevancy score will record the clear price of the ad. This is defined differently from other second price auctions:

Clear Price = (Ad Rank of Runner Up / Winner's Relevancy Score) + $0.01

Reporting on Relevancy Score

Currently, relevancy score data is only available on impression and click objects in data shipping.

Relevancy scores will appear as the RelevancyScore parameter on the object.