VOD Analytics API

VOD Analytics API

Video on Demand (VOD) Analytics & APIs

Below are guidelines and API information for VOD analytics.

VOD Analytics Workflow

Below is the workflow for reporting analytics for video assets viewing.
  1. Register the device with the device registration service, and store the deviceId in localstorage and/or cookies on the device. So that next time user comes to the app there is no need to register it again, as well as its availability for the calls below.
  2. [OPTIONAL] If the response from Publishing API -> getAssetPlaybackUrls has the field useSscs and the value is true then we also need to send an additional "idle" event every 9 mins (regardless of whether the video is being played or not). Make the first request in this interval before the player initializes.
  3. Make an "player_load" call when the player is loaded
  4. Make a "player_start" call once the video starts playing
  5. Repeatedly make "player_active" calls at 1 minute intervals (while the video is playing, it should not do so if it is paused)
  6. Make a "player_stop" call if video completes OR is paused
  7. Make a "player_seek" call if video is seeked during playback
Details of the calls involved in above workflow are given in below sections.

Device Registration

Method: GET

Parameters:

Parameter Name
Requirement
Parameter Value
organizationId
Mandatory
ID of the organization/account

Note: For react native mobile applications define a "User-Agent" header for the request based on below plugin:

Response:
  1. {"status":"ok","deviceId":"6a9f3478-e948-3ad3-9bc2-2d84a8d7ac73"}
Remember to store this deviceId in cookies and/or local storage so that it is used for any subsequent calls or sessions, so the device registration should be done only once.

Video Analytics Events

Method: GET

Parameters:

Parameter Name
Requirement
Parameter Value
Additional Notes
organizationId
Mandatory
ID of the organization/account

deviceId
Mandatory
ID of the device

assetId
Mandatory
ID of the video asset being played

createdBy
Mandatory
Value of the createdBy field for this asset
Available in response of Publishing API -> getAssetPlaybackUrls
eventName
Mandatory
Acceptable values:
- player_load
- player_start
- player_active
- player_seek
- player_stop
- idle (note additional info)
- Note that "idle" event is only in case when Publishing API -> getAssetPlaybackUrls contains a useSscs field as true
- "idle" event MUST be sent before player is initialized
duration
Mandatory
Duration of asset (in milliseconds)
Exception: use 1 for the "player_load" event. Use correct value for all other events
currentPosition
Mandatory
Current position of playback (in milliseconds)

folderIds
Mandatory
IDs of the folders this asset belongs to (if any, otherwise 0)
Usually can be parsed for the "folders" property of Publishing API ->  getAsset or getAssets responses.
userId

Mandatory (If user logged in)
ID of the logged in user




    • Related Articles

    • Analytics API (ENG)

      INTRODUCTION This API stores video access/usage statistics for the linear channels and vod items. API PATH /api/analytics API METHODS ADDING NEW RECORD Adds a new analytics record of either on-demand video usage or linear channel viewing statistics ...

    • Video-On-Demand Analytics

      Introduction In contrast to the analytics of live streams and events, real-time is not as important in the analytics of streaming or on-demand videos. It can be used in OVP, OTT and Event uses cases, but also with HbbTV and Smart TV environments when ...

    • Event and Webinar Analytics

      Introduction Event and Webinar analytics are used mostly by Icareus Video Cloud event customers: enterprises', public organizations', and third sector organizations' event organizers. However, it can also be used for different pay-per-view event ...

    • OEMBED API (ENG)

      INTRODUCTION This API is used to query for oEmbed objects for video page URL(s) on Icareus Suite sites. Note Suite oEmbed API only supports JSON responses for now API PATH /api/oembed API GET OEMBED OBJECT REQUEST /api/oembed Parameters: Name Value ...

    • Live Audience Analytics API

      Live Audience Analytics & APIs Below are guidelines and API information for Live analytics for channels. Live Analytics Workflow Register the device with the device registration service, and store the deviceId in localstorage and/or cookies on the ...