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.