### Deprecated

This version of relevancy scores has now been deprecated. Please see [this page](https://dev.kevel.com/docs/relevancy-score) for the latest version of relevancy scores.

### With Kevel's Relevancy Score functionality

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:

```json
"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 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. |

### Create a New Priority

```curl
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.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `CustomRelevancyScore` | int | N | Sets the relevancy score. Must be between 1 and 1000. |

### Create a New Flight

```curl
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 an ad

To set a relevancy score on an 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. |

### Create a New Ad

```curl
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.

#### Using a single override

```javascript
ados_addPlacement(...).setOverrides({"ads": {"123456": {"relevancyScore": 333}}})
```

#### Using multiple overrides

```javascript
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.

#### Using a single override

```json
"overrides": {
   "ads": {
      "123456": {
         "relevancyScore": 333
      }
   }
 }
```

#### Using multiple overrides

```json
"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**:

### Calculating AdRank

```text
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:

### Calculating Clear Price

```text
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.