DCR Chromecast browser SDK

Engineering Portal / Digital / DCR & DTVR / DCR Chromecast browser SDK

1. General Cast architecture

See https://developers.google.com/cast/docs/developers

Sender App

is a user controlled JavaScript/HTML5 application which can run on browsers in mobile or desktop devices.

Receiver App

is an HTML5/JavaScript application placed at a custom URL that handles communication between the Sender app and the Chromecast device.

2. Cast scenarios

2.1 Pure casting scenario

In the Pure casting scenario the video plays on the Chromecast device, while playback stops on the sender app
The sender app should not pass any Nielsen API calls once the pure casting scenario starts. All Nielsen API calls are handled by the receiver app.

2.2 Chromecast mirroring scenario

In the Chromecast mirroring scenario the video plays on both the sender and receiver apps.

3.Sender App JavaScript - Nielsen Browser SDK implementation

3.1 General

By adding the below cast-specific API calls alongside the standard implementation of the Nielsen Browser SDK, a sender app can pass appropriate cast-specific metadata.

3.2 API calls

3.2.1 updateOTT

The below call should be made to the Browser SDK whenever the player switches from not casting to casting and vice versa.

nolSDKInstance.ggPM('updateOTT',contentMetadataObject);

Use the updateOTT method to notify the casting BrowserSDK instance whether the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected or disconnected (indicated by "ottStatus").

When the OTT device is connected, call updateOTT with "ottStatus": "1" as well as a set of OTT device related parameters in the contentMetadataObject.

var contentMetadataObject ={
        type: "content",
        ottStatus: "1",
        ottType: "casting",
        ottDevice: "chromecast",
        ottDeviceName: "Google Chromecast",
        ottDeviceID: nolSDKInstance.getId(),
        ottDeviceManufacturer: "Google",
        ottDeviceModel: "ChromeCastModel",
        ottDeviceVersion: "1.0.0" 
    };

When the OTT device is disconnected, call updateOTT with “ottStatus”: “0”.

3.2.2 getOptOutStatus() and sessionId

Assign the below mediaInfo metadata parameters in the target load so that they may be passed to the receiver at the beginning of the casting session.

mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
mediaInfo.metadata.kGCKMetadataNlsKeyOptout   = nolSDKInstance.getOptOutStatus(); //OptOut status

Below is a sample code snippet on how the sender browser app should retrieve and relay the information from sender to receiver app.

        var mediaInfo = new chrome.cast.media.MediaInfo(
         this.mediaContents[mediaIndex]['sources'][0], 'video/mp4');

        mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
        mediaInfo.metadata.metadataType = chrome.cast.media.MetadataType.GENERIC;
        mediaInfo.metadata.title = this.mediaContents[mediaIndex]['title'];
        mediaInfo.metadata.length = this.currentMediaDuration;
        mediaInfo.metadata.images = [
            {'url': MEDIA_SOURCE_ROOT + this.mediaContents[mediaIndex]['thumb']}];

        /*Adding custom parameters in metadata to be passed to receiver*/
        mediaInfo.metadata.kGCKMetadataNlsKeyDeviceID = nolSDKInstance.sessionId; //Session Id
        mediaInfo.metadata.kGCKMetadataNlsKeyOptout   = nolSDKInstance.getOptOutStatus(); //OptOut status

        var request = new chrome.cast.media.LoadRequest(mediaInfo);
          castSession.loadMedia(request).then(
           this.playerHandler.loaded.bind(this.playerHandler),
           function (errorCode) {
             this.playerState = PLAYER_STATE.ERROR;
             console.log('Remote media load error: ' +
               CastPlayer.getErrorMessage(errorCode));
          }.bind(this));

4. Summary - Sequence of API calls

Below is the sequence of API calls from the beginning to the end of casting.

SENDER side

1) If the video is playing only on the Sender App, the standard Nielsen Browser SDK API calls should be invoked.
2) Once a user presses the cast icon and if the video is playing already, call browser sdk end() api.
3) Inform the Browser SDK about the Chromecast's status (connected or disconnected) by calling updateOTT() and passing metadata object.
4) Retrieve the OptOutStatus and sessionId.
5) Pass the optOutStatus and sessionId into the MediaInfo metadata object.
6) When the Start casting (the video should be stopped on the sender device).

RECEIVER side

Playback has started at ChromeCast device (TV).
7) Retrieve the MediaInfo metadata sent by the sender device.
8) Instantiate the Browser SDK.
9) Pass content/ad metadata by calling loadMetaData().
10) Send updateOTT event to BSDK receiver instance, to relay the sender OTT metadata ( kGCKMetadataNlsKeyDeviceID and kGCKMetadataNlsKeyOptout) received from sender app.
11) Pass content/ad playheads every second by calling setPlayheadPosition().
12) Based on the user's interactions or the playlist state, call stop() (once paused) or end() (once the content or casting has ended).

SENDER side

Casting has ended and playback resumes on the sender device.
13) Start a new session by calling content/ad loadMetaData().
14) Continue sending API calls as usual.

Below is a sample code snippet on how the receiver app should retrieve the ottMetadata received from sender apps and relay the information to receiver BSDK instance.

sampleplayer.CastPlayer.prototype.onLoad_ = function(event) {
var senderMetadata = event.data.media.metadata,
sessionId = senderMetadata.kGCKMetadataNlsKeyDeviceID,
optout = senderMetadata.kGCKMetadataNlsKeyOptout;
  this.cancelDeferredPlay_('new media is loaded');
  this.load(new cast.receiver.MediaManager.LoadInfo( (event.data),  event.senderId));
	var contentMetadata = {
         	   "type": "content",
          	  "dataSrc": "cms",
           	 "assetid": "vid-123",
          	  "assetName": "Test video",
           	 "program": "Test program",
          	  "title": "Clickbaby",
          	  "length":”60”,
          	  "segA": "CustomSegmentValueA",
          	  "segB": "CustomSegmentValueB",
          	  "segC": "CustomSegmentValueC"
	};
      window.nolSDKInstance.ggPM('loadMetadata', contentMetadata);
	   var ottMetadataObject ={
			ottStatus: "1",
			ottType: "casting",
			ottDevice: "chromecast",
			ottDeviceName: "Google Chromecast",
			ottDeviceID: nolSDKInstance.getId(),
			ottDeviceManufacturer: "Google",
			ottDeviceModel: "ChromeCastModel",
			ottDeviceVersion: "1.0.0", 
			kGCKMetadataNlsKeyOptout : optout,
		    kGCKMetadataNlsKeyDeviceID : sessionId	
		  };
window.nolSDKInstance.ggPM('updateOTT', ottMetadataObject);};

Chromecast Developer Documentation: <https://developers.google.com/cast/docs/developers>
Browser SDK API Reference: <https://engineeringportal.nielsen.com/docs/Browser_SDK_API_Reference>