Synamedia Iris allows you to use the data that you have about your customers to create product offerings of value to advertisers. This data can include context and content-related information such as genre, language, rating, and so on. There are many features in Synamedia Iris to target your customers for campaigns. These include inventory targeting such as channel awareness, and segment targeting such as audience attributes.
Another way of targeting your customers is Key-Value Pair (KVP) targeting. KVP Targeting allows Synamedia Iris users to define their own keys and their corresponding values so that the data can be used to help advertisers and buyers reach their intended audience. KVP allows users to define custom targeting and use them in campaign targeting. This allows users to enhance their advertising offerings and design more effective campaigns.
The key-value pairs can also be included in the ad decision requests. When an ad decision request comes in from an OTT app that contains key-values information, the campaigns that target those key-values are eligible to serve for that ad request. To use the KVP targeting feature, Synamedia Iris Ad Manager provides back-office API services that you can use to ingest to your own custom key-value sets.
Note: The KVP targeting feature is only available for OTT. Synamedia Iris users must use APIs to create their own key-value pairs.
To start using KVP in Synamedia Iris, use the following steps:
1. Add New Keys and Values
Before you create campaigns in Synamedia Iris, you must ensure that you have a predefined set of key-value pairs. You can use the KVP API service to create keys and their associated values, and then use the campaign targeting API service to create your targeting. The keys defined must consist of only URL-safe characters. If that key already exists for this tenant in the system, then an HTTP status error code 400 will be returned. You can use the predefined KVPs for campaign targeting when you already know the possible range of values. For example, for a predefined key called genre, you can enter values such as drama, sports, comedy, and so on. When you select KVP targeting for the campaign, select genre as the key and drama as the value. The KVP remains hard coded in the ad request.
Note: While defining keys, only alphanumeric and "_" characters can be used for the key ID. Alphanumeric and "_" "." "~" "-" characters can be used for the values. Note that the keys and values are case-sensitive.
The values for keys should include only URL-safe characters. Also, when you define keys using the KVP API service, these keys will be available for campaign targeting in Synamedia Iris. Only keys that were pre-defined using the KVP service will be available when you create campaigns.
2. Include Key-Values in Iris Ad Request
For KVP targeting to work, a user should ensure that the ad request or VAST calls contain the desired keys and values. The following is the example format to predefine a key in an ad request tag. **kvp={key}~{commaSeperatedListOfValue} The following is an example of a predefined key: kvp=genre~sports,basketball&kvp=parentalRating~R The following is an example of an ad request: "/adServer/{tenantId}/vast/vod?subscriberId=simba&deviceId=rafiki_iphone&deviceProfile=gatingTest_devProfile&sessionId=07f06c75-2996-491a-8ca4-dbaffa9672f7&transactionId=db9c5419-6aaf-47e4-8ff5-d08a16262b58&contentId=basketball1&kvp=genre~sports,basketball&kvp=parentalRating~R
3. Target Key-Values in Campaigns
To use KVP targeting in your campaigns, a user must use the campaign API service to define the KVP targeting object. KVP targeting for the campaign is based on data that is received as part of the VAST decision request. The keys should be defined in advance using the inventory/KVP APIs. The keys are validated against predefined keys and the values can be predefined or free text. The rule is tested against the decision request parameter. If the rule is evaluated as false or if some of the parameters are missing in the request, the campaign will not be used for this decision. The rule of KVP operations is defined as Boolean expressions. The following table describes the supported operators:
Operator | Description | Campaign Definition |
|---|---|---|
== | The Equal sign expresses "is". Use the Equal sign between a key and its value. For example: genre==sports This key-value pair can target a subscriber watching sports content. | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "genre == sports" } } |
!= | The exclamation mark followed by the Equal sign expresses "is not". For instance, consider this expression: genre!=drama. This input would target all other values of "genre", except "drama". | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "genre != drama" } } |
&& | For example: gender==male&&genre==sports This targeting captures male users who are interested in sports. | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "gender == male && genre == sports" } } |
|| | The "OR" operator. Use this operator to connect expressions when only one expression among them needs to be true. For example: genre==sports||gender==male | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "genre == sports || gender == male" } } |
, | Comma. Same as the "OR" operator. Can be used instead of "OR". For example; genre=sports,drama | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "genre == sports,drama" } } |
() | Parentheses are used to give precedence to specific sub expression (like in math). For example: (genre==drama||genre=sports)&&(rating==R) is not the same as (genre==drama)||(genre==sports&& rating=R). | Campaign metadata will include : "targeting" : { "kvpTargeting" : { "rule" : "(genre==drama || genre=sports) && (rating==R) " } } |
Consider that you are running an OTT entertainment channel called E-Hub. Your advertiser wants to target customers who watch sports programs but also watch drama. When people create a user account for E-Hub, their personal information is stored in the E-Hub database. To help your advertisers show ads to relevant users, you need to set up key-values. For example, you can define a key called "genre" and add values that represent all your channel’s contents, as described in the following table:
Keys | Values |
|---|---|
Genre | Comedy Drama Action Animation Sports |
Interests | Fashion Sports Languages Drama |
To ensure that the key-values pair work, users should append the key-value to the ad request. When a subscriber watches your OTT channel, the operator can extract the relevant key-value information from the database for that subscriber and pass it programmatically to the ad request. From Iris Ad Manager, you can then target the lineup items for your advertiser that include the required key values:
Key: genre
Values: sports And
Key: interests
Values: drama
When signed-in subscribers browse your OTT app or website, an ad request is sent to Iris Ad Manager with all the keys and values. If the subscriber request matches a defined key-value pair, then an ad creative from the KVP campaign is served. If not, another campaign is selected based on other criteria.
