Custom Parameters (Key-Value Pairs)

Publishers can create customized targeting packages using key-value pairs and sell them at higher CPMs than their regular inventory.

Key-value pairs can be used for a variety of purposes:

  • Page identification on a website
  • Audience segments
  • Content targeting
  • Target ad inventory

A key-value pair consists of two elements:

  • Key (such as “category”)
  • Value (“sport”).

Key-value pairs are attached directly to the player tag and passed to buyers through the bid request, and provide context that helps advertisers identify high-performing segments.

The Primis platform supports targeting based on key-value pairs during campaign setup. After selecting either the Prebid or RTB ad integration type, you can define custom parameters for targeting.

Primis Custom Parameters Structure

The custom parameters field in the campaign setup has input text that is composed of two parts:
[key hierarchy]=[macro]

Key Hierarchy

  • The [key hierarchy] is built from words separated by dots
  • Keys must not include any numbers or special characters
  • The key structure represents the full hierarchy inside the bid request object in which you intend to implement the custom data

For example:
“video.ext.custom” is a legitimate key.
Note that the custom key hierarchy must begin at the top of the hierarchy.

Macro (Placeholder)

The [macro] is the placeholder that indicates to the player which value should be placed instead of it.

There are three types of placeholders:

  • Predefined key-value parameters embedded in the player tag
  • Dynamic values
  • Dynamic keyword macro for ad requests

Predefined KV params - can be embedded in the player tag, allowing the publisher to control specific campaign bid request values. For example:
Tag: liveView.php/……?kv_1=automobile
Campaign setup: video.ext.cat=${KV_1}
This will result in the “automobile” value passing through the specific campaign bid request in the “video.ext.cat” hierarchy

Dynamic values - embedded in the campaign setup as a placeholder macro and replaced in real-time by the corresponding value. For example:
Campaign setup: video.player_type=${PLAYER_TYPE}
In real-time, the client code will replace the ${PLAYER_TYPE} macro in the bid request structure with the flow status of the player at that time (docking or floating)

Dynamic keyword macro for ad requests- Create a macro that extracts keywords from the video content and includes them in the ad request under the cust_param field in Google Ad Manager.
Integration Type: Google IMA SDK
Keyword Extraction Logic:
Preroll – Extract keywords from the upcoming content that will be played.
Midroll – Extract keywords from the currently playing content.
Second Preroll (after 'Primis Next') – Extract keywords from the next content video in the queue.
The extracted keywords will be passed in bid requests under cust_params, allowing them to be mapped within GAM.
Macro Format: ${CONTENT_KEYWORD_COLLECT}
For example:
Campaign setup: video.content_keywords=${CONTENT_KEYWORD_COLLECT}
In real time, the client code will replace ${CONTENT_KEYWORD_COLLECT} in the bid request with the relevant keywords based on the content position.

URL Parameters - Single/ multiple predefined parameters embedded in the URL can be passed with the bid stream, for example, site.com?token1=rch1_primis_direct&token2=rch2_primis_direct10.
Dynamic values embedded in the campaign setup as a placeholder macro - ${URL_PARAM_1} / ${URL_PARAM_2} are replaced in real-time with the corresponding value - token1=rch1_tech_primis_direct&token2=rch2_tech_primis_direct10.

Vid Index - Vid Index, a numerical value indicating the unique position or order of a video within a playlist or a collection of videos, can be passed with the bid stream. For example, for the first video’s position, vidindex=1 is passed, and for the second video, vidindex=2, etc.
Dynamic values embedded in the campaign setup as a placeholder macro, ${VIDEO_SEQUENCE_NUMBER}, are replaced in real-time with the corresponding value - vidindex=1, vidindex=2, etc.

The index number can be used for various purposes, such as controlling playback order, referencing specific videos, or implementing custom functionality within the player interface.