Player Side REST API

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,
but in the latter, you must let us know the identifier you generated.</>

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&amp;
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&amp;
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,
but in the latter, you must let us know the identifier you generated.</>

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&#038;
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