1 - API Integration: Getting Started

IRIS.TV's API can be used to generate recommendations in continuous play and static display envirnoments

The API has three main calls:

  1. Watch
  2. Update
  3. Next

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. This call generates a list of recommendations as well as an Experience value, which is used to track all user behavior in the video stream.

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.

The Next Call is made to refresh or extend the viewing experience. This should be made in three situations: (1) if a viewer reaches the end of the videos made on the Watch call; (2) if a viewer clicks Thumbs Up on a video; (3) if a viewer clicks Thumbs Down on a video.

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
number: The number of recommendations to be returned in the response
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
recs_only: Set to `true`. [If `false` then the Watch call will also indicate the start of play of the initial video.] 

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

Sample Workflow

Client Incandenza, requesting five assets in a call, 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&number=5&access_token=996JVD321AZ&user_id=BTORW&recs_only=true&client_token=99999

Response:

jQuery191028397097534104254_1407970311998({
'success': true,
'next': [
{
'iris_id': '2140j908',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_1.mp4',
'platform_id': '241YOFG',
'title': 'Birdman International Trailer',
'release_date': '2014-08-01 18:34:33 UTC'
},
{
'iris_id': '51084789cd5f272312231105',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_2.mp4',
'platform_id': '343YOW',
'title': 'Snow Owl Short Film',
'release_date': '2012-10-22 12:30:58 UTC'
},
{
'iris_id': '539a5ba7f09c3f00172310bb',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_3.mp4',
'platform_id': '780YOTSDB'',
'title': 'Blue Heron Teaser Trailer',
'release_date': '2014-06-12 20:51:53 UTC'
},
{
'iris_id': '53cdc6233459980016231012',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_4.mp4',
'platform_id': '9019YOPW',
'title': 'Nelson Simcoe Clip',
'release_date': '2014-07-20 19:51:07 UTC'
},
{
'iris_id': '51084760cd5f2723122310a1',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_5.mp4',
'platform_id': '89YWQMD',
'title': 'Life & Times Trailer',
'release_date': '2012-11-30 05:48:51 UTC'
},
{
'iris_id': '53814f1af1585f0032231014',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_6.mp4',
'platform_id': '46YDPA',
'title': 'Paleo Diet International Trailer',
'release_date': '2014-05-24 19:33:28 UTC'
}
],
'experience': '53ebec0d321d0690858dw5r1',
'sc':false
})

The “Next” field will contain an echo of the asset passed on the Watch call as the first video. After the echoed asset, the requested number of assets will be displayed.

After the list of assets is the “experience” value. The experience will be passed on all Update and Next calls that follow the Watch call.

Video Parameters In Watch Response:

iris_id: IRIS.TV’s Reference ID for video
platform: the name of the publisher
content_URL: Link to video file on publisher’s CMS (only available if sent in during import process)
platform_id: the Reference ID from the publisher’s CMS
title: Title of video via publisher’s CMS
release_date: Date when asset could be recommended
reviewed: Date when asset was reviewed by IRIS.TV staff
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.
default_recs:
 Notifies if recommendations are not based on the current asset. Only appears if set to “true.” Occurs when asset passed through in the Watch Call is unknown

 

If default_recs=true, then the API response will NOT include the initial asset. The response will ONLY include the requested recommendations.

 

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

 

Documentation for creating access tokens

 

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.

 

No Assets in Next Field

Problem: No assets in library.
Solution: Contact IRIS.TV representative and check import schedule.

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 current stream of videos (generated on Watch call)
access_token: created via OAuth 2 standard
user_id: ID associated to the individual user
client_token: string of characters to authorize the client
behavior: field that covers any user behaviors. Note: multiple behaviors can be included in one Update call

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)

See watch call parameters:

recs_only: If set to `true`, an Update call containing behavior[play] should be sent on the initial video
If `false` then the Watch call will also indicate the start of play of the initial video.

Sample API Call:

User BTORW starts second video on site Incandenza

Call

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

Response

{
"success": true,
"behavior": {
"play": 1
},
"experience": "53ebec0d321d0690858dw5r1"
}

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.

Next Call

The Next call requests continues an experience with a new set of recommendations based upon user interaction with the content. A next call should be made whenever the recommends need to be refreshed while maintaining the same experience value.

Scenarios for a Next Call:
1. User watches all assets in the initial Watch Call
2. User responds with either a like or dislike that alters the recommendation calculation

 

NOTE: When making a Next call after an Update call, make sure the Next call comes after receiving the IRIS API response from the Update call.

platform_id: the reference ID from the publisher’s CMS
platform: the name of the publisher
number: the number of recommendations to be displayed in the response
access_token: created via OAuth 2 standard
user_id: ID associated to the individual user
client_token: string of characters to authorize the client
experience: Value that defines current stream of videos (generated on Watch call)

Sample Workflow

Client Incandenza requests a refresh in recommendations for user PGOAT

 

Call

http://api.iris.tv/next?platform_id=46YDPA&platform=Incandenza&number=5&access_token=996JVD321AZ&user_id=PGOAT&client_token=99999&experience=53ebec0d321d0690858dw5r1

Response

jQuery191028397097534104254_1407970311998({
'success': true,
'next': [
{
'iris_id': '51084789cd5f272312231105',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_6.mp4',
'platform_id': '908JOL',
'title': 'The Grapefruit Theif',
'release_date': '2012-10-22 12:30:58 UTC',
'reviewed': '2013-02-05 23:02:24 UTC',
},
{
'iris_id': '539a5ba7f09c3f00172310bb',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_7.mp4',
'platform_id': '874KFR'',
'title': 'The Bird Baron Trailer',
'release_date': '2014-06-12 20:51:53 UTC'
},
{
'iris_id': '53cdc6233459980016231012',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_8.mp4',
'platform_id': '891RGB',
'title': 'Orson Welles UK Teaser Trailer',
'release_date': '2014-07-20 19:51:07 UTC'
},
{
'iris_id': '51084760cd5f2723122310a1',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_9.mp4',
'platform_id': '908MAR',
'title': 'Early Morning Moon Clip',
'release_date': '2012-11-30 05:48:51 UTC',
'reviewed': '2013-09-06 22:35:10 UTC',
},
{
'iris_id': '53814f1af1585f0032231014',
'platform': 'Icandenza',
'content_url': 'http://www.credenza.com/asset_10.mp4',
'platform_id': '56YLI',
'title': 'C Grodin International Trailer',
'release_date': '2014-05-24 19:33:28 UTC'
}
],
'experience': '53ebec0d321d0690858dw5r1'
})

Video Parameters In Next Response:

iris_id: IRIS.TV’s Reference ID for video
platform: the name of the publisher
content_URL: Link to video file on publisher’s CMS (only available if sent in during import process)
platform_id: the Reference ID from the publisher’s CMS
title: Title of video via publisher’s CMS
release_date: Date when asset could be recommended
reviewed: Date when asset was reviewed by IRIS.TV staff
experience: Value that defines the current stream of videos.

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
Solution: Double check your client token. If still invalid, contact IRIS.TV support.

No Assets in Next Field

Problem: No assets in library.
Solution: Contact IRIS.TV representative and check import schedule.