Standard Content Feed Ingestion

Below are lists of required ingest methods and metadata requirements for adding contextual segments to your video content. If you are not able to fit these specifications, please talk to your account management regarding other options for ingesting assets.

Method for Video Asset Metadata Ingestion

IRIS.TV prefers the following format for feed ingestion:

• JSON

Once you have sent IRIS.TV a feed to access your assets, IRIS.TV will ingest your video data into your secure account.

Asset Ordering and Pagination

Pagination

IRIS.TV recommends using an `offset` parameter and a page `limit` parameter. Here's an example of a feed URL using the parameters:

http://my.site/video_feed.json?offset=2000&limit=1000

• This can easily be implemented with (for example) the following SQL:

  SELECT * FROM video_assets
  
  ORDER BY updated_at DESC
  
  LIMIT 1000
  
  OFFSET 2000

A maximum limit of 1,000 is recommended, but not required. Please notify IRIS.TV of your maximum limit.

Asset Ordering

• We ask that clients order the feed by the videos last update_date
• For feeds with episodic content, publishers should ensure that episode assets are published individually. Assets should not be nested under a series parameter.

There are two requirements for this to work well:

1. If any of the fields you are providing via your feed are updated for an asset, you must ensure that that asset will go to the top of the feed (by updating the `updated_at` column for that asset, for example).
2. If none of the fields have changed for a given asset, then the JSON or XML representation of that asset in the feed also must not change.

Metadata Requirements

Required Metadata Formatting

Metadata should be formatted as follows:

• Metadata field names should match IRIS term below (i.e. if "name" exists, it should be changed to "title").
• If metadata field does not exist for an asset, return a null value.
• Text fields do NOT include escaped HTML characters. Example of escaped characters can be found here:  https://www.w3schools.com/tags/ref_urlencode.ASP
• Timestamps should be formatted as UTC milliseconds since the UNIX epoch.

Required Metadata Fields

These fields are necessary to create contextual segments for your assets. If title, GUID, and asset_url (link to the video file) are not sent, no context can be provided. The rest of the fields can have null values.

• Title : The video assets title.
• GUID: The unique numeric identifier of asset.
  • Publisher should confirm that GUID will be used to retrieve IRIS data.
• Video URL: A link to asset’s video file from either your CDN or CMS (mp4 or m3u8 format is required).
• Description: A description for the asset.
• Tags: Any keywords or tags associated with the asset. This should also include categories that are included in publisher's taxonomy.
• Original Air Date: The date of asset's original airing (requirement for CTV VOD/streaming pubs) (UTC milliseconds since epoch).
• Publish Date: The date/time when the asset record was first published on your web site or video application (UTC milliseconds since epoch)
• Update Date: The date/time when the asset record was last modified (required) (UTC milliseconds since epoch).
• Duration: The duration of the video in seconds.
• Thumbnail URL: The URL for thumbnail or image that you want to represent your asset. For best results, image should be at least 300 pixels (width) with a 16:9 ratio.
• If the following data exists please add: 
  • State: The active or inactive state of the video in your CMS.
  • Show Name: The title of the show.
  • Season Number:  The numerical season that the episode is in. This should be formatted as an integer.
  • Episode Number:  The order that the episode is in for the season. This should be formatted as an integer.
  • Genre: Topic categorization of the asset (ex. action, documentary).
  • Language: The language of audio in the video.
  • Transcript URL: url that refers to transcript or closed caption data.

Optional Meta Data

This data can improve the organization and categorization of your assets.

• Expiration Date: The date when video should no longer be accessible to viewers  (UTC milliseconds since epoch).
• Sensitive/Explicit Content: A flag to show a video contains sensitive or explicit content.
• Rating: TV or MPAA rating.
• Above is a guide.  IRIS.TV will accept additional meta data fields.  Contact your IRIS.TV TAM for more information during the onboarding process.

Sample Asset Meta-data from a Publisher

{  
"guid": 5331690110001,  
"title": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",  
"description": "Donec congue orci vel ante posuere consectetur. Vestibulum vel eros velit. In suscipit arcu nec lectus posuere sagittis.",

"dates"   :  {
             "publish_date" : 1487717574502,
             "original_air_date" :1487717574502,
             "update_date" :  1487717955852,
             "expiration_date" :  1487717955852
             },      
  "url" : {
            "asset_url" : "http://media.matrix.com/videos/video_mp4/3200k/p30695rq216952rpnn.mp4",
            "thumbnail_url" :  "http://media.matrix.com/videos/thumbnails/p30695rq216952rpnn.jpg",
            "transcript_url":  "http://media.matrix.com/videos/transcript/p30695rq216952rpnn.txt",
          },
  "show": {
            "genre" :"Sports",
            "name" : "The Show",
            "season_num" : 2,
            "episode_num" : 3,
            },  
"show_name" : The Show,
"language" : English
"tags": [  
          "alex rodriguez",  
          "new york yankees",  
          "mlb"   
         ],  
"duration": 30805,  
"economics": "AD_SUPPORTED",  
"categories": [  
                "Baseball"  
              ],  
"itemState": "ACTIVE",

},

Special Instructions

Instructions for null values: if a metadata field has a null or value does not exist, pass that as a null value in the feed

• Formatting instructions
  • • Text: do not include escaped characters
    • Date - UTC milliseconds from epoch

After the Initial Video Data Ingestion

Once the initial ingest is complete, IRIS.TV will provide you with credentials to start the Context Script or Context API integration. These credentials include:

• Client Token: used to authenticate your asset library. Required for both the Context Script and Context API integrations.
• Access Token: used to authenticate with the API. Required for the Context API integration.

The integration will also require the use of a platform_id. The platform_id is mapped in from the unique ID field during the ingest. Once you have received the above credentials from IRIS.TV, please move to Retrieving Contextual Data for Context Only Clients.