Relevancy Score

📘

Summary

With Kevel's Relevancy Score functionality, you can directly influence the ad selection process in an auction using your own relevancy/quality score data. Kevel then uses your supplied relevancy score data in combination with eCPM number to calculate an Ad Rank, which is used by the Ad Decision Engine to rank ads.

What is a relevancy score?

Relevancy score is a Decision API capability that allows you to directly influence ad selection in an auction using your own relevancy/quality score data.

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 CPC for clicks, but their ads are not relevant to the user, 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. An ad with a higher relevancy score will win an auction over similarly priced ads.

Example use cases:

• Using your own click/conversion propensity models to influence the auction so that ads that the user is likely to click on receive an increased likelihood of selection
• Providing an artificial boost smaller advertisers in auctions to allow them to compete with high-budget advertisers
• Punishing promoted items that have poor organic performance
• Punishing low-margin products so that they need to bid more to be selected

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.

📘

Note

An ad that does not have a defined relevancy score will have a default relevancy score of 500. As such, ads that have a relevancy score of less than 500 are considered to be punished, whereas ads that have a relevancy score of over 500 are seen as favourable over similarly priced ads.

Using relevancy scores

You can set relevancy scores in the Decision API request in each placement, mapped against:

• On creative template fields/values
• On an AdvertiserID / CampaignId / FlightID / AdId

Mapping relevancy scores to creative template fields and values

If you are using creative templates to store creative metadata (such as product attributes), you can use a creative template field and define how relevant its values are. For example, assuming your creative template had a field ctCategoryName - you may want to define relevancy scores that represent how likely you believe the user is to engage with each category.

"relevancy": {
  "idAttribute": {
    "ctCategoryName": {
      "shoes": 831,
      "shirts": 645,
      "jeans": 505,
      "sportswear": 402
    }
  }
}

In the example above, any ad that has a ctCategoryName that contains one of the following values shoes, shirts, jeans, or sportswear will receive a boost or penalty in the auction process.

Relevancy scores don't require the use of AdQuery, although the two are often used in combination with each other, particularly for Auction as a service use cases, as demonstrated below:

"adQuery": {
  "ctProductId": {
    "in": [
      "123",
      "234",
      "345",
      "456",
      "567"
    ]
  }
},
"relevancy": {
  "idAttribute": {
    "ctProductId": {
      "123": 832,
      "234": 645,
      "345": 505,
      "456": 811,
      "567": 484
    }
  }
}

Mapping relevancy score to entity IDs (advertiser, flight, ..)
Alternatively, you can map relevancy scores to one of the following entity IDs: advertiserId, campaignId, flightId, adId.

For example:

"relevancy": {
  "idAttribute": {
    "adId": {
      "123456": 403,
      "234567": 901,
      "345678": 133,
      "456789": 482
    }
  }
}

📘

Note

We do not suggest sending relevancy score data for multiple idAttributes - only a single attribute will be used for relevancy score calculations.

Relevancy Score and Revenue

Unlike standard auctions, auctions that use relevancy scores will choose the ad with the highest AdRank:

AdRank = eCPM * RelevancyScore

First price auctions

In a first price auction, revenue-generating events 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

Relevancy score data is available on impression and click objects in data shipping. Relevancy scores will appear as the RelevancyScore parameter on the object.

The Decision API can also return information regarding the relevancy score calculation for each ad that has been selected to serve. To enable this, please contact your account manager. You must then specify "includeRelevancyData": true in the Decision API request body.

Example data:

"relevancy": {
    "attributeName": "ctProductId",
    "attributeId": "3",
    "rank": 1515,
    "orderedAttributes": [
        "ctProductId"
    ],
    "scores": {
        "ctProductId": {
            "1": 0.832,
            "2": 0.645,
            "3": 0.505
        }
    }
}

📘

Note

Site relevancy is not available at decision request time. This scoring can be set up to give sites a different weight. See details here.

Legacy Relevancy Scores

If you have used Relevancy scores prior to 20th November 2022 - you may want to refer to the legacy relevancy score documentation instead.