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

GEThttp://stats.streamhub.io/api/player/

Ticker Parameters

The table below lists all parameters required within the REST API ticker calls.

Ticker ParametersRequired?Description
sessionIdmandatory

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/

randomSessionKeymandatoryCurrent session UUID (create for each user session)
partnerIdmandatoryStreamhub Partner ID (per partner)
analyticsIdmandatoryStreamhub Analytics ID (a unique id that has been provided to you)
publicIdmandatoryA unique identifier for the media currently playing
playerIdmandatory

A unique identifier for each of your video players.

We can generate those identifiers for you or you can do it yourself,
but in the latter, you must let us know the identifier you generated.</>

agentmandatoryBrowser user agent string
startTimemandatoryA integer which increments minutely during each media playback. A startTime of 0 must be sent when media first begins to play.
bitrateoptionalBitrate of currently playing media
isLiveoptionalVOD or live boolean (true or 1,false or 0)
refUrloptionalWhere 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.
locationUrloptionalInformation about the URL of the page that embed the video player
parentPublicIdoptionalID unique to currently playing media (this would be the channel if publicId is a program)
osoptionalUser operating system
isFullScreenoptionalWhether in fullscreen boolean

Example Ticker Call

GEThttp://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

GEThttp://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 ParametersRequired?Description
eventmandatoryThe event type (see available events in table below)

Event Types

The table below lists all available events.

Event NameDescription
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

GEThttp://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

GEThttp://stats.streamhub.io/api/content/

Content Parameters

The table below lists all parameters required within the REST API content calls.

Content ParametersRequired?Description
partnerIdmandatoryStreamhub Partner ID
analyticsIdmandatoryStreamhub Analytics ID (per contentowner)
contentOwnerNamemandatoryName of the content owner
publicIdmandatoryID unique to currently playing media
typemandatorychannel,player,program,stream,series
titlemandatoryTitle or name of the item being submitted
descriptionoptionalSummary of the content being submitted. (ie: Todays episode will focus on …)

Content Types

You can submit various types of content using this API

TypeDescription
programProgram information
channelChannel
seriesSeries information
playerPlayer information (ie: MiniPlayer)
streamStream information (ie: HD Live Stream 1)

Example Content Call

GEThttp://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

GEThttp://stats.streamhub.io/api/advertisement/

Advertisement Parameters

The table below lists all parameters required within the REST API content calls.

Ad ParametersRequired?Description
sessionIdmandatory

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/

randomSessionKeymandatoryCurrent session UUID (create for each user session)
partnerIdmandatoryStreamhub Partner ID
analyticsIdmandatoryStreamhub Analytics ID (per contentowner)
publicIdmandatoryID unique to currently playing media
parentPublicIdmandatoryParent publicId of the media currently playing (the program/channel the ad is shown for).
playerIdoptional

A unique identifier for each of your video players.

We can generate those identifiers for you or you can do it yourself,
but in the latter, you must let us know the identifier you generated.</>

agentmandatoryBrowser user agent string.
percentilemandatoryPercentage of the ad that has been watched.
Tick should be sent at 0,25,50,75,100%.
stIdOptionalService 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]
refUrloptionalWhere 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

top

© Copyright Streamhub