Legacy Relevancy Score

🚧

Deprecated

This version of relevancy scores has now been deprecated. Please see this page for the latest version of relevancy scores.

📘

With Kevel's Relevancy Score functionality, you set the Relevancy Score at the Flight or Ad level. Kevel then uses this number to calculate an Ad Rank, which is used by the Ad Decision Engine to pick ads. Kevel 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 Kevel 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 Kevel, 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
   }

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.

curl -X POST -H "X-Adzerk-ApiKey:<API-KEY>" https://api.kevel.co/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.

curl -X POST -H "X-Adzerk-ApiKey:<API-KEY>" https://api.kevel.co/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.

curl -X POST -H "X-Adzerk-ApiKey:<APIKEY>" https://api.kevel.co/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 the ados_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.