API Reference

Initializaion & Configuration

Player Initialization

The Streamrail SDK for JavaScript doesn't have any standalone files that need to be downloaded or installed. Instead, simply include a short piece of regular JavaScript in your HTML that will asynchronously load the SDK into your pages. The async load means that it does not block loading other elements of your page.

Once the player is loaded, you'll want to configure it: what content to play, what ads to schedule, what is the API key in use, etc. This page will discuss the general configurations for the player. (For configuration, video content, or ads, please see the appropriate sections.)

Loading The Player's Script

The most straightforward way to include the player is by placing its JavaScript right after the body tag. Then add a bit of code that tells the player some basic commands, like where to render (to which div the player should attach), which content to play, etc.

Functions in the global scope

Function Description
SR Calls to SR to generate a new instance of the player
window.srAsyncInit When the StreamRail SDK is loaded, it looks for this function in the global scope and is triggered automatically when found. You should only make calls to the SR function after this function has been triggered.
SR_NS internal steamrail object
srvjs internal steamrail object


The SR Function

When calling the SR function, you may supply the following parameters:

Parameter Description
containerID The ID of the div to which you would like the player to attach. This parameter is optional, but recommended. You should omit it only if integrating the player inside an SSP, in the instance that you want the player to bind itself to the top of the document. Under these circumstances, omit this parameter and use the configuration object parameter as the single parameter when calling SR.
configuration object A configuration JSON that contains all the required settings for the player (content, ads, apiKey, etc.), or just the playerId if this player was generated via the platform site.


The following snippet shows how loading the script is done. You place a <script> tag in the page that loads StreamRail, and then implement the srAsyncInit function by creating a new instance of the player (var player = SR(...)).

copy

<div id="video-container"></div>
<script>
	// the srAsyncInit function is automatically triggered by the sdk when the player is ready
	window.srAsyncInit = function() {
		// supply SR with a containerID ('video-container') and a configuration object
		var player = SR('video-container', {
			...
			...
			...
		});
	}
	// async load of the sdk
	(function(d, s, id) {
		var js, srjs = d.getElementsByTagName(s)[0];
		if (d.getElementById(id)) {
		return;
	}
	js = d.createElement(s);
	js.id = id;
	js.src = 'https://sdk.streamrail.com/player/sr.ads.js';
	srjs.parentNode.insertBefore(js, srjs);
}(document, 'script', 'streamrail-jssdk'));
</script>

	    					
	    				


The Configuration Object

This is the object supplied as the second (or the single) parameter to the SR function, which contains the full configuration of the player.

General Settings

Property Type Default Description
apiKey string N/A The key supplied by your account manager. This is a GUID format string that is used to identify this player.
viewability bool false Should the player start playing the ad/content only when it's viewable? If this property is set to true, the player will pause and play according to it's viewability.
scaleMode string 'fit' 'original' or 'fit'. In case the player's aspect ratio is different than the video's aspect ratio, this property designates if the player should maintain the original aspect ratio or fit it to the container accodingly.
adRequestThrottle number 1000 This is the minimum time between subsequent waterfall calls (or ad tag calls in case there is no waterfall). So for example in breakingAds mode, once the waterfall finishes (even if this happens quickly because there is no fill), the process of requesting the waterfall again won't happen if the time defined here had not elapsed. Default is 1000 (1 sec).
loop bool false If loop is set to true, the ad and/or content video will automatically restart when it ends or if an ad error exists. In every iteration, an ad request is made to the ad server specified in the ads section (so new ads might show up).
bgColor string 'black' Hex color for the background of the video. Black is "Hollywood style" and fits most use cases, but you may wish to use 'transparent' if you are displaying the video in-text.
autoplay bool false Should the video start as soon as the player is ready? on desktop - this is for both ads and content. On mobile - this is for ads only - unless you set contentAutoplay to true
contentAutoplay bool false Mobile only: should the player also autoplay the content? if this is not set to true, only the ad will autoplay
muted bool false for content, true for ads Should the player start muted? The default is to start muted for ads and unmuted for content.
width int the container's width Player width; set to be the container's width by default (responsive).
height int the container's height Player height; set to be the container's height by default (responsive).
noLoader bool false remove the default loader/spinner
watermark object N/A Optionally include a watermark overlay. The object should look like so: { url: 'link.to.your.watermark.png' }. You can also make it clickable, as well as set its link URL and position.

Example:
{ file: 'https://www.streamrail.com/images/logo-small.png', xpos: 0, ypos: 0, xrepeat: 0, opacity: 0.5, clickable: true, url: 'https://www.streamrail.com/'}
content object N/A The content video and its settings. It may contain the URL of the video, a linkUrl (destination if the player is clicked on while the content is playing), a title, description, ID, categories, and keywords for the video (automatically sent to the ad server if there are ads).

Example:
content: { url: 'https://sdk.streamrail.com/demos/debugger/nasa_is_with_you_when_you_fly.mp4', id: 'nasa_is_with_you_when_you_fly.mp4', title: 'NASA Video', description: 'Cool video by NASA', keywords: 'space,nasa', categories: 'science' },
playlist array of content objects or string (URL to a JSON file containing an array of content objects) N/A Similar to the content node specified on top, but as an array. The player will play one item after the other. If a pre-roll is specified, an ad reqeust to the ad server will be made before each item in the playlist queue.

Ad-Related Settings

Property Type Default Description
hideContentBeforePreRoll bool false If there is fast-loading video content, the poster of the video content will be seen before the ad loads. You can set this to "true" in order to prevent this behavior, and a black poster will be shown until the preroll starts.
adCancelTimeout int (time in milliseconds) N/A By default, if there is an ad error, the player will continue to the next ad or to the content (or, if there is no content and the loop mode is set to true, the player will continue trying to get ads). If you would like to put a hard time limit for showing the ad (i.e. if an ad is not shown and does not throw an error after a while), you can set this value. This option is suitable for cases in which you have a single pre-roll and do not want the users to wait for too long before continuing to the content video.
dontRepeatOnAdError bool fakse By default, the player will try to get ads if an ad error (or an empty VAST response) exists until adCancelTimeout is applied. If you would like the player to quit trying to fetch ads after just one try, set this value to 'true'.
breakingAds object N/A { enabled: true/false, hideContentControls: true/false, on: 'AdImpression' (default - not mandatory)} When enabled, the content video starts instantly. Meanwhile, ads are fetched in the background continuously (from the specified pre-roll tag), and as soon as an ad is received, it is pushed to replace the content. When the ad finishes, the content resumes and the process repeats itself.
You can specify the on attribute to tell the player on which ad event to break into the content (AdImpression is the default).

If you want to limit this behavior, you can set the minTimeBeforeAds (minimum, time before the ads start, in milliseconds) and minTimeBetweenAds (minimun time between consecutive ads, in milliseconds).
macros object N/A An object containing macros coming from an SSP. All parameters here are urlencoded and sent to the ad server. Some special macros are reported to Streamlytics for reporting under your account (placement, campaignid, sellerid, etc.).
passpack object N/A Optionally, if an ad error is received or ad time out is fired, you can use passback to inject custom HTML onto the page. For example, this code may contain a banner ad.

Example:
passback: { on: 'AdError', html: '&lt;div style="color:red"&gt;hello passback &lt;/div&gt;' },
ads object N/A The ads object contains a schedule object and a skip object. See the following section ("The ads object").

The ads object

Property Type Default Description
schedule array of ads to be scheduled N/A An array containg ads to be scheduled. Each object is an ad object. The object contains a position ('pre-roll', 'mid-roll' or 'post-roll' and a server node, containing the url of the ad ("tag"), a waterfall of ads (tags array) or a waterfall ID.

example1: a pre-roll schedule
ads: { schedule: [{ position: 'pre-roll', server: { tag: someAdTag } }] }

example2: multiple pre-rolls schedule
ads: { schedule: [{ position: 'pre-roll', server: { tag: someAdTag1 } }, { position: 'pre-roll', server: { tag: someAdTag2 } }] }

example3: pre-roll, mid-roll, post-roll
ads: { schedule: [{ position: 'pre-roll', server: { tag: someAdTag1 } }, { position: 'mid-roll', server: { tag: someAdTag2 } }, { position: 'post-roll', server: { tag: someAdTag3 } }] }

example4: Google IMA SDK
ads: { ima: { url: someImaUrl } }

example5: a pre-roll schedule, with a waterfall of two tags (the first one won't load - "bad.xml", the second one yields ads)
ads: { schedule: [{ position: 'pre-roll', server: { tags: ['https://sdk.streamrail.com/demos/vast/bad.xml', 'https://sdk.streamrail.com/demos/vast/vast.xml'] } }] }

skip object N/A Append a custom skip control that allows the user to skip the ad (even if it's a Flash VPAID ad). You can configure how long the user has to wait before skipping is enabled, the skip text, and whether or not the skip function is enabled (which it isn't by default).

Example:
skip: { enabled: true, seconds: 10, btnText: 'Continue' },

Examples

An ad schedule with a pre-roll, a mid-roll, and a post-roll. Ad and content are autoplayed and muted by default.

copy

<script>
  window.srAsyncInit = function() {
    SR({
      partnerID: 'your streamrail api key',
      muted: true,
      content: {
        linkUrl: 'http://www.streamrail.com/',
        url: 'https://www.streamrail.com/videos/new/bg.mp4',
        title: 'streamrail website'
      },
      autoplay: true,
      ads: {
        schedule : {
          position: 'pre-roll',
          server: {
            tag: 'https://sdk.streamrail.com/demos/vast/vast.xml'
          }
        },
        {
          position: 'mid-roll',
          startTime: '00:00:10',
          server: {
            tag: 'https://sdk.streamrail.com/demos/vast/vast.xml'
          }
        },
        {
          position: 'post-roll',
          server: {
            tag: 'https://sdk.streamrail.com/demos/vast/vast.xml'
          }
        }]
      }
    });
  };

  (function(d, s, id){
     var js, fjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://sdk.streamrail.com/player/sr.ads.js";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'streamrail-jssdk'));
</script>

	    					
	    				

An ad schedule with a pre-roll and rotation of 4 (pre-roll tag is requested 4 times before content is played).

copy

<script>
  window.srAsyncInit = function() {
    SR({
      partnerID: 'your streamrail api key',
      muted: true,
      content: {
        linkUrl: 'http://www.streamrail.com/',
        url: 'https://www.streamrail.com/videos/new/bg.mp4',
        title: 'streamrail website'
      },
      autoplay: true,
      ads: {
        schedule: [{
          position: 'pre-roll',
          rotate: 4,
          server: {
            tag: 'https://sdk.streamrail.com/demos/vast/vast.xml'
          }
        }]
      }
    });
  };

  (function(d, s, id){
     var js, fjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://sdk.streamrail.com/player/sr.ads.js";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'streamrail-jssdk'));
</script>

	    					
	    				

Google IMA SDK Integration

The player is fully integrated with Google's IMA SDK. All of the general settings hold when it comes to working with IMA, but there are several differences:

  • When Google IMA SDK is used, it is Google's SDK that actually plays the ad. The player mostly passes settings to the IMA SDK.
  • Because the IMA SDK is playing the ad, the standard player functions and methods rely on IMA's implementation for different APIs. (For example, when you ask the player to mute, the player asks Google IMA to mute via the API.)
  • Events emitted by the IMA SDK are passed to the player and are emitted by the player so that your code can capture them.
  • On mobile web, autoplay is not possible for IMA SDK (since it is not the StreamRail player actually playing the ad).
For the above reasons and although not mandatory, it is recommended that if you work Google IMA that you try to stick to working with standard VAST tags (e.g. DFP VAST tags) instead of tags that require IMA.


Configuring the player with IMA

The only difference in configuration is that you must let your player know that the tag inputed is an IMA tag and not a standard VAST tag. Since the IMA tag contains information about the schedule (pre-, mid-, post-roll), it is the only thing the player needs to determine the schedule.


Example:


copy

<script>
  window.srAsyncInit = function() {
        var imaUrl = 'http://pubads.g.doubleclick.net/gampad/ads?sz=640x480&' +
        'iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&' +
        'impl=s&gdfp_req=1&env=vp&output=xml_vmap1&unviewed_position_start=1&' +
        'cust_params=sample_ar%3Dpremidpostpod%26deployment%3Dgmf-js&cmsid=496&' +
        'vid=short_onecue&correlator=';

        var player = SR('video_container', {
            partnerID:'api-docs',
            companion: false,
            autoplay: true,
            viewability: true,
            content: { // optionally show a content video after the ad
                url:'https://sdk.streamrail.com/demos/debugger/nasa_is_with_you_when_you_fly.mp4',
                id: 'nasa_is_with_you_when_you_fly.mp4',
                title: 'Nasa Video',
                description: 'Cool video by nasa',
                keywords: 'space,nasa',
                categories: 'science'
            },
            ads: {
                ima : {
                    url : imaUrl    
                }
            }
        });
  };

  (function(d, s, id){
     var js, fjs = d.getElementsByTagName(s)[0];
     if (d.getElementById(id)) {return;}
     js = d.createElement(s); js.id = id;
     js.src = "https://sdk.streamrail.com/player/sr.ads.js";
     fjs.parentNode.insertBefore(js, fjs);
   }(document, 'script', 'streamrail-jssdk'));
</script>