The following information is pertaining to how the IRIS.TV Contextual Video Marketplace activates contextual data partners segments for open auction buying via contextual data partners pre-bid integration in the DSP.
How Contextual Data Partners Utilize the iris_id:
Available contextual data partners will can utilize the Context API route to match an iris_id to a source_url. The contextual data provider will be responsible for querying IRIS.TV when they receive an unknown iris_id.
How to Retrieve an iris_id
Contextual data partners have two scenarios when they will want to match a source_url to an iris_id, which include:
-
Retrieving the source_url for an unknown iris_id: If a data partner receives an unknown iris_id from a DSP they will need to retrieve the source_url for the unknown iris_id.
-
Retrieving a new iris_id once the current one has expired: If a data partner want to actively retrieve a new iris_id to replace an expired iris_id.
The parameters necessary for both approaches above include:
-
access_token : created using the OAuth standard. IRIS.TV will provide the data partner with a client ID and client secret.
-
iris_id : The iris_id sent to the data partner by the DSP.
Generating an Access Token for the API Route
IRIS.TV will provide you with a client_key and client_secret that can be used to generate access tokens. The tokens can be generated via a POST request to https://context.iris.tv/auth_token
{
"client_key" : "<API client key provided by Iris>" ,
"client_secret": "<API client secret provided by Iris>"
}
$ curl -D - -H "Accept: application/json" -H "Content-Type: application/json" -X POST -d '{"client_key":"3j4l2jj4fsd","client_secret":"sososecret"}' "https://context.iris.tv/auth_token"
{"success":true,"data":{"client_key":"3j4l2jj4fsd","token_type":"bearer","access_token":"eyJlbmMiOiJsdfgklsjfOUALJALWxnIjoiZGlyIn0..kYctrS6fFQRaiElhBKWr0A.e2TfXODBL8lMDBuvbZzI22KApmx5H3YmYk-zn7JVFEw.1IyRygtE2fPmW0fTyqV9DF6njmDKdPe504NwsEKW0Ys"}}
An access token can be used for up to ten days. Once you've generated your access token, you can use the API route to retrieve the source_url for an iris_id.
Context API Route for Retrieval:
https://context.iris.tv/refresh?access_token=98aljfalmn&iris_id=iris_46akanap
If the iris_id is valid, IRIS.TV will return a 200 response with the following parameters:
-
iris_id - the asset’s current iris_id.
-
iris_id_expires_at - the UNIX timestamp when the current iris_id will expire.
-
iris_id_next - the iris_id that will be valid after the current one expires.
-
iris_id_next_expires_at - the UNIX timestamp for when the next iris_id will expire.
-
source_url - the source_url for the video asset.
Retrieving the source_url For an Unknown iris_id:
When data partners receive an unknown iris_id from a DSP, they will query IRIS.TV with the unknown iris_id. IRIS.TV will respond with the following:
{ "source_url" : "https://www.sample_pub_url.mp4",
"iris_id" : "iris_78191lilpoe019",
"iris_id_expires_at" : 1588291200,
"iris_id_next" : "iris_1897aflaja",
"iris_id_next_expires_at" : 1588401200
}
Retrieving a New iris_id When One Has Expired:
Once the TTL for an asset’s iris_id has passed, the data partner will query IRIS.TV with an asset URL to retrieve the new iris_id.
-
Data Partner should make a call to the IRIS API
-
IRIS API will respond with the following:
{ "source_url" : "https://www.sample_pub_url.mp4",
"iris_id" : "iris_78191lilpoe019",
"iris_expires" : 2020-04-15 17:55:07.582Z,
"iris_id_next" : "iris_1897aflaja",
"iris_id_next_expires_at" : 1588401200
}
Data partners are responsible for the above workflows and how they operate with their DSP partners in order to have valid iris_ids at all times.