Contents
Overview
The Streamhub REST API provides a RESTful service for sending video usage reporting data to the Streamhub analytics platform.
Even though it is possible to report statistics by sending them to the raw REST service, the effort to be compliant to the service methods would be significant.
Instead, we highly recommand to create a bridge plugin using our javascript library. See Creating your own plugin for the Streamhub Analytics platform
Resources
Four types of calls can be made to the API: Ticker, Events, Content and Ad.
Tickers (Player API)
Ticker calls keep track of media views.
There is 2 different strategy we use to collect the tick and it depends on whether we know or ignore the media content actual duration value.
If the media duration is know, we send ticks to the collector at a frequency equal to 1% of media duration but we never go below a 1 tick per second frequency.
So for example if a video is 3 minutes we will send ticks every 2 second, if the video is 1 hour, the ticks will be sent every 36 seconds
In the second case, which occurs if we don’t know at runtime the media content duration information (for a Live content most likely) ticks will be sent:
- Every 5 seconds (0sec, 5sec, 10sec…) during the first minute of video playback
- Every minute after the first minute until the end of the playback
Resource
| GET | http://stats.streamhub.io/api/player/ |
Ticker Parameters
The table below lists all parameters required within the REST API ticker calls.
| Ticker Parameters | Required? | Description |
|---|---|---|
| sessionId | mandatory | User session UUID (Unique Universal Identifier). Should be generated once and stored in a cookie or browser’s local storage (minimum of 3 months). An UUID online generator: https://www.uuidgenerator.net/ |
| randomSessionKey | mandatory | Current session UUID (create for each user session) |
| partnerId | mandatory | Streamhub Partner ID (per partner) |
| analyticsId | mandatory | Streamhub Analytics ID (a unique id that has been provided to you) |
| publicId | mandatory | A unique identifier for the media currently playing |
| playerId | mandatory | A unique identifier for each of your video players. We can generate those identifiers for you or you can do it yourself, |
| agent | mandatory | Browser user agent string |
| startTime | mandatory | A integer which increments minutely during each media playback. A startTime of 0 must be sent when media first begins to play. |
| bitrate | optional | Bitrate of currently playing media |
| isLive | optional | VOD or live boolean (true or 1,false or 0) |
| refUrl | optional | Where the user came from before he reached the player page ? This is provided via the document.referrer function. It has some limitations for players embedded using iframes methods. |
| locationUrl | optional | Information about the URL of the page that embed the video player |
| parentPublicId | optional | ID unique to currently playing media (this would be the channel if publicId is a program) |
| os | optional | User operating system |
| isFullScreen | optional | Whether in fullscreen boolean |
Example Ticker Call
| GET | http://stats.streamhub.io/api/player/?sessionId=1234& randomSessionKey=1234&partnerId=1234&playerId=1234&isLive=false&refUrl=http://www.url.com&agent=Chrome&operatingSystem=Windows&publicId=1234& bitrate=500&startTime=0&isFullScreen=false |
Events (Player Event API)
Event calls record user interaction and media playback events, such as a user clicking on a player pause button or a media reaching playback completion.
Resource
| GET | http://stats.streamhub.io/api/playerevent/ |
Event Parameters
The parameters sent along with the api/playevent requests are the same ones used for the ticker requests, but with one extra parameters ‘event’ which provide a bit of extra information.
| Event Parameters | Required? | Description |
|---|---|---|
| event | mandatory | The event type (see available events in table below) |
Event Types
The table below lists all available events.
| Event Name | Description |
|---|---|
| player_start | |
| player_error | |
| player_buffering | |
| player_play_completed | |
| player_play_end | |
| player_play_seek | |
| click_epg_next | |
| click_epg_previous | |
| click_epg_more | |
| click_share_button | |
| click_share_twitter | |
| click_share_facebook | |
| click_player_fullscreen | |
| click_player_theater | |
| click_player_normalscreen | |
| click_player_popout | |
| click_share_email | |
| click_player_mute | |
| click_promotion | |
| click_promotion_close | |
| show_promotion | |
| click_play | |
| click_pause | |
| click_stop | |
| click_next | |
| click_previous | |
| click_cc_on | |
| click_cc_ff |
Example Event Call
| GET | http://stats.streamhub.io/api/player/?sessionId=1234& randomSessionKey=1234&partnerId=1234&playerId=1234& isLive=false&refUrl=http://www.url.com&agent=Chrome& operatingSystem=Windows&publicId=1234&bitrate=500&startTime=0& isFullScreen=false&event=player_start |
Content (Content API)
Content API allows you to submit titles and descriptions for content used in the player. It can be called at any time.
Resource
| GET | http://stats.streamhub.io/api/content/ |
Content Parameters
The table below lists all parameters required within the REST API content calls.
| Content Parameters | Required? | Description |
|---|---|---|
| partnerId | mandatory | Streamhub Partner ID |
| analyticsId | mandatory | Streamhub Analytics ID (per contentowner) |
| contentOwnerName | mandatory | Name of the content owner |
| publicId | mandatory | ID unique to currently playing media |
| type | mandatory | channel,player,program,stream,series |
| title | mandatory | Title or name of the item being submitted |
| description | optional | Summary of the content being submitted. (ie: Todays episode will focus on …) |
Content Types
You can submit various types of content using this API
| Type | Description |
|---|---|
| program | Program information |
| channel | Channel |
| series | Series information |
| player | Player information (ie: MiniPlayer) |
| stream | Stream information (ie: HD Live Stream 1) |
Example Content Call
| GET | http://stats.streamhub.io/api/content/?publicId=1234&partnerId=streamhub&type=program&title=Introduction%20To%20Streamhub&description=In%20this%20video%20we%20introduce%20streamhub%20to%20the%20general%20public |
Ads (Advertisement API)
The Advertisment API allows you to submit metadata about an Ad played in the player.
It can be called at any time.
Resource
| GET | http://stats.streamhub.io/api/advertisement/ |
Advertisement Parameters
The table below lists all parameters required within the REST API content calls.
| Ad Parameters | Required? | Description |
|---|---|---|
| sessionId | mandatory | User session UUID (Unique Universal Identifier). Should be generated once and stored in a cookie or browser’s local storage (minimum of 3 months). An UUID online generator: https://www.uuidgenerator.net/ |
| randomSessionKey | mandatory | Current session UUID (create for each user session) |
| partnerId | mandatory | Streamhub Partner ID |
| analyticsId | mandatory | Streamhub Analytics ID (per contentowner) |
| publicId | mandatory | ID unique to currently playing media |
| parentPublicId | mandatory | Parent publicId of the media currently playing (the program/channel the ad is shown for). |
| playerId | optional | A unique identifier for each of your video players. We can generate those identifiers for you or you can do it yourself, |
| agent | mandatory | Browser user agent string. |
| percentile | mandatory | Percentage of the ad that has been watched. Tick should be sent at 0,25,50,75,100%. |
| stId | Optional | Service Type ID. Accepts: [1 Live – Free, 2 Live – Subscription, 3 Live – Voucher, 4 Live – Pay Once, 5 VOD – Free, 6 VOD – Subscription, 7 VOD – Voucher, 8 VOD – Pay Once, 9 Download – Free, 10 Download – Subscription, 11 Download – Voucher, 12 Download – Pay Once] |
| refUrl | optional | Where the user come from before he reached the player page. This is provided by document.referrer but with some limitations for players embedded using iframes methods. |
Example Advertisement Call
| GET | http://stats.streamhub.io/api/advertisement/?publicId=1234&parentPublicId=5678& sessionId=3DF715F1-0D60-C092-28FD-6192BE3F7D61&randomSessionKey=03EBC66D-88EC-6AA9-995E-6192BE400C87& percentile=0.5&refUrl=http://player.streamhub.tv/jw/& agent=Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.85 Safari/537.36&partnerId=XYZ&analyticsId=ABC&playerId=d17491b6-8392-43f4-9cce-79af221e539d |
© Copyright Streamhub