API Metrics

This details how to use the Adaptive Stream API to record user behavior without recommendations. Please contact your account manager before implementing it.

The API has two calls:

  1. Watch
  2. Update

The Watch Call is made when a viewing experience is initiated. This can either happen when a user clicks on an asset or the first video is played. A viewing experience is defined by a stream of videos that are played continuously. 

The Update Call is made to send any information on viewer behavior to IRIS.TV. These behaviors include: Play, Video Complete, Skip, Pause, Thumbs Up, Thumbs Down.

All IRIS.TV API calls require an access token created using the OAuth 2 standard.

Watch Call

A Watch Call should be made whenever a viewing experience is initiated. This can happen when a viewer clicks on an asset or when the first video is auto-played.

The necessary parameters for a watch call are:

platform_id: The reference ID from the publisher’s CMS
platform: The name of the publisher
access_token: Token created via OAuth 2 standard
user_id: A unique ID generated to be associated to the individual user
client_token: Authentication string associated with each client
metrics_only: Set to `true`. 

Please reference the Parameter Glossary for more information on these parameters.

Sample Workflow

Client Incandenza starts an experience for User BTORW.

Documentation for creating access tokens

SSL:

The API supports both standard HTTP and HTTPS calls with SSL/TLS encryption.

Call:

https://api.iris.tv/watch?platform_id=241YOFG&platform=Incandenza&access_token=996JVD321AZ&user_id=BTORW&metrics_only=true&client_token=99999

Response:

(
{
"success": true,
"next": [],
"sc": true,
"experience": "5f6a750ce33a810a9665eb"
}

)

The “Next” field is expected to be blank.

At the end of the response is the "experience" value. The experience will be passed on all Update calls that follow the Watch call.

Video Parameters In Watch Response:

experience: Value that defines the current stream of videos. Note: a new experience is generated on every watch call.
sc: Boolean value that indicates whether or not a cookie has been set.

Errors

Invalid Access Token

Status Code: 401 Unauthorized
IRIS.TV Response: “The access token is no longer valid”
Problem: Access Token is invalid or has expired
Solution: Create a new access token using OAuth 2

Invalid Client Token

Status Code: 401 Unauthorized
IRIS.TV Response: “IRIS API: Check your authentication credentials”
Problem: Client Token is Incorrect
Solution: Double-check your client token. If still invalid, contact IRIS.TV support.

Update Call

After the experience has been started with the Watch call, the Update call is used to send any user interaction to the IRIS.TV API.

Necessary Parameters for an Update Call:

platform_id: the reference ID from the publisher’s CMS
platform: the name of the publisher
experience: Value that defines the current stream of videos (generated on Watch call)
access_token: created via OAuth 2 standard
user_id: ID associated with the individual user
client_token: a string of characters to authorize the client
behavior: field that covers any user behaviors. Note: multiple behaviors can be included in one Update call

metrics_only: boolean with the value set to `true`

List of Standard Behavior Parameters:

behavior[play]: Video Starts Playing (Value 1)
behavior[video_complete]:Video Complete (Value 1)
behavior[pause]:Video Paused (Value 1)
behavior[next]:Video Skipped/Next (Value 1)
behavior[next_auto]:Next Video Played in Autoplay Mode(Value 1)
behavior[thumbs_up]: User clicked liked (Value 1)
behavior[thumbs_down]: User clicked disliked (Value 1)
behavior[percentage_watched]:Percentage Video Watched (Value 0.0 -­ 1.0)

Sample API Call:

User BTORW starts the second video.

Call

http://api.iris.tv/update?platform_id=343YOW&platform=Incandenza&access_token=996JVD321AZ&user_id=BTORW&client_token=99999&experience=5f6a750ce33a810a9665eb&metrics_only=true&behavior[play]=1

Response

{
"success": true,
"behavior": {
"play": 1
},
"experience": "5f6a750ce33a810a9665eb"
}

Errors

Invalid Access Token

Status Code: 401 Unauthorized
IRIS.TV Response: “The access token is no longer valid”
Problem: Access Token is invalid or has expired
Solution: Create a new access token using your Client Credentials

Invalid Client Token

Status Code: 401 Unauthorized
IRIS.TV Response: “IRIS API: Check your authentication credentials”
Problem: Client Token is Incorrect

No Experience Included

Status Code: 400 Bad Request
IRIS.TV Response: "Message: invalid experience"
Problem: Experience is missing from update call
Solution: Double-check the parameters being sent in on the update call. If still invalid, contact IRIS.TV support.