NAV
Platform SDKs
Android SDKApple TV Data APIChromecast SDKFireTV SDKRoku SDKTvOS SDKWeb Player SDK v3Web Player SDK v3 with MCP IntegrationiOS SDK
     
Service APIs
Feeds APILive Streaming APIVOD Encoder APIVast Conditioning API

Anvato Chromecast Receiver Framework (ACRF)

Quick Start

Prerequisites

You need the the following for integration:

Deployment Locations for anvreceiver.min.js

How to Build the Partner Receiver Application

As a partner Chromecast app developer, you build your application UI in HTML5/ CSS/ JavaScript as you normally would; this is called the Partner Application. However, please ensure that you follow the following guidelines:

  1. Include Chromecast Receiver and Media Player libraries
  2. Include Anvato Chromecast Receiver Framework script anvreceiver.min.js
  3. Provide your view url in the data-view-url attribute of anvreceiver.min.js script tag
  4. Provide your stylesheet for the Partner Application
  5. Provide your Partner Application script

Including anvreceiver.js script instantiates Anvato Chromecast Receiver Framework and utilizes the anvr namespace to expose API methods and callbacks to get partner application configuration.

The Structure of Partner Application Script

A typical partner application script consists of the following sections:

Debugging the application

In order to use the APIs and the services the Receiver App is providing and debug the application, the bundle must be deployed to a remote location as is. Using this location the bundle must be registered as a development application. And corresponding App ID must be entered in a Chromecast enabled Anvato Player SDK.

A Chromecast device that is registered under the same account with the development application must be connected to a screen and its IP address must be detected.

Once the player app utilizing Anvato Player SDK is up and running, Chromecast streaming must be enabled. The debug logs can be retrieved using Chromecast console on http://CHROMECAST_IP:9222

At this point you are ready for developing your Chromecast receiver using the Anvato Receiver App.

Publishing the application

Publishing the application involves turning off any debug modes, minifying the JavaScript and CSS files, deploying the customized bundle to a remote location, and finally registering the application.

Development Guide

Receiver Configuration

ACRF accepts the receiver configuration set to anvr.config. The configuration has the following fields:

Name Type Description Required
videoPlaceholderId String HTML5 video element ID YES
debug Boolean Used for turning on debug logs NO
customNamespaces Array of Strings Custom messaging namespace(s) NO
recommendations Object Recommendations plugin configuration (applies to MCP VOD Content) NO
plugins Object ACRF plugin configuration is passed in this field NO

Plugins

Adobe Heartbeat Analytics

The following configuration must be used for enabling Heartbeat Analytics service including custom metadata tracking.

Plugin Name Parameters Definition
heartbeat marketingCloudId Marketing Cloud ID provided by Adobe.
customTrackingServer This parameter is used for specifying the servers processing the custom metadata (Typically Adobe Visitor and AppMeasurement servers). Multiple tracking servers seperated by comma can be entered.
trackingServer Tracking server for Heartbeat provided by Adobe.
jobId Job ID provided by Adobe.
account account ID provided by Adobe.
publisherId publisher ID provided by Adobe.
version Must be set to “1.5” for the latest heartbeat implementation.

Processing Receiver States

Receiver states are notified using anvr.onStateChanged callback. The SDK user is expected to update the view accordingly. Additionally the SDK user is supposed to notify the ACRF about the end of transition.

Sending this notification is possible in 2 ways:

Listening the Receiver Events

Listening the ACRF events is possible by setting listener callback under anvr namespace. The event format is shown below for a sample event:

{
   "name": "RECEIVER_TYPE_SET",
   "time": "11:32:44:164",
   "info": "Chromecast player type has been set based on the content",
   "args": [
      "vod"
   ],
   "recipient": [
      "16:client-8220",
      "16:client-73691",
      "16:client-65131",
      "16:client-70690"
   ]
}
Name Type Description
name String Event name
time String Event time
info String Event definition
args Array Event payload
recipient String The recipient sender IDs

Detailed information for each event is given in the Reference Guide section.

Receiving the Error Events

The ACRF Errors are dispatched using the event channel mentioned above. Still conforming to the same format an error message has the following payload in the args field:

[errorCode, errorMessage, isCritical]

A sample error event:

["RCVR020", "Custom message bus associated with the provided namespace does
not exist while attempting to call sendCustomMessage", false]

Detailed information is given in the Reference Guide section.

Messaging Through Custom Channel

A custom channel can be used for receiving and sending messages to the application layer of a sender. In order to use custom channel, its namespace(s) must be registered to customNamespaces under anvr.config.

ACRF will establish the requested messaging channels when anvr.init() is called.

Once above steps are completed, the custom channels will be available for use whenever anvr.onReady callback is called for the first time.

The existence of custom message bus can be verified optionally by calling anvr.getCustomMessageBus(customNamespace). This will return a reference to the custom message bus instance for the given namespace.

The custom messages can be received using the anvr.onCustomMessage callback with arguments namespace, sender and message to identify the origin and the message. In order to send custom messages anvr.sendCustomMessage(namespace, sender, message) method must be used with the arguments specifying the name and destination.

Alternatively, the SDK user may prefer using the custom message bus instance for a more manual approach.

Establishing Connection From Sender to Receiver Framework

Anvato Chromecast solution allows applications to communicate with the Anvato Chromecast Receiver Framework without using the Anvato Chromecast API available in the SDK. This flow requires only static methods in the SDK. It does not require SDK to be initialized. This method can be summarized as follows:

  1. Sender application connects to a device and starts the receiver application.
  2. Sender application establishes a custom channel for the following namespace. "urn:x-cast:com.anvato.chromecast"
  3. Sender application uses static SDK methods to generate "verification" payload using the SDK methods and forwards it to the receiver application through the custom channel.
  4. Upon receiving the custom message, the receiver framework returns a dictionary to indicate the status of the verification. If successful, the dictionary contains the token information that should be used in future communications
  5. At the final step, when the application wants to play content, it needs to attach another custom message to the chromecast media information object (e.g., GCKMediaInformation in IOS). In order to obtain the custom payload, the application can use the following API methods:

Android:

AnvatoSDK.getChromecastCustomPayload(String anvack, String token, String videoID)

iOS:

AnvatoSDK.getChromecastCustomPayload:(NSString *)anvack withToken:(NSString *token) withMcpVideoID:(NSString) videoID

Android:

AnvatoSDK.getChromecastCustomPayload(String anvack, String token, String videoID)

iOS:

AnvatoSDK.getChromecastCustomPayload:(NSString *)anvack withToken:(NSString *token) withMcpVideoID:(NSString) videoID

Reference Guide

Callbacks

anvr.onReady()

Called when initialization is completed. When this is called, useful API methods become available under anvr namespace.

Parameters: Name Type Description
name String Parameter name

Returns:

Type: String

anvr.onCustomMessage(namespace, sender, message)

This callback is called when a sender sends a message through the custom channel(s) that are passed into the configuration under anvr.config.

Parameters: Name Type Description
namespace String custom channel namespace
sender String sender Id
message String message content

anvr.onStateChanged(state)

This callback is called when there is a change in the ACRF current state. The application is expected to make changes to the receiver UI based on the requested state.

Parameters: Name Type Description
state String Receiver state

Returns:

Type: Boolean or undefined

anvr.onTimeUpdated(currentTime, totalTime, contentType, adBreakIndex, adIndex)

Provides the current time index and the duration of the content or ad based on contentType. Additionally, adBreakIndex and adIndex are provided if the contentType is “ad” and index information is available.

Advanced use cases such as playing ad stitched VOD require using the data sent via related events such as AD_BREAKS event.

Parameters: Name Type Description
currentTime Number Current time index in seconds
totalTime Number Total time in seconds
contentType String “ad” or “content”
adBreakIndex Number Ad break index
adIndex Number Ad index inside an ad break

Returns:

Type: Boolean or undefined

anvr.onSeekRequested(timeIndex)

Called when the receiver receives a seek request. This callback is used if there is a need to change the seek index or perform some tasks when there is a seek request.

Parameters: Name Type Description
timeIndex Number Seek index in seconds

Returns:

Type: Number

API Methods

anvr.init()

Injects the provided partner view to ACRF, instantiates AnvatoChromecastReceiverManager and AnvatoChromeCastVideoPlayer with the provided configuration within ACRF and finally starts the main flow that is followed by events/callbacks and interacted using API methods. Must be called when the partner application configuration and callbacks are provided.

anvr.sendCustomMessage(namespace, sender, message)

Sends a custom message to the specified sender in the provided namespace.

Parameters: Name Type Description
namespace String custom channel namespace
sender String sender Id
message String message content

anvr.onStateTransitionCompleted()

Called when the state transition is asynchronous and it is completed.

anvr.getCustomMessageBus(namespace)

Gets the custom message bus associated with the provided namespace

Parameters: Name Type Description
namespace String custom channel namespace

Returns:

Type: cast.receiver.CastMessageBus

RPCs

ACRF allows calling specified API methods from a sender using remote procedure call via the namespace urn:x-cast:com.anvato.chromecast.

RPC message must have the format shown on the side:

{
    type: "rpc",
    content: {
        name: fnName,
        args: args
    }
}

toggleCaption

Used for toggling on/off closed captions. Once this RPC is called, ACRF will dispatch CAPTION_STATUS with the same arguments as payload. And this event will be repeated for subsequent senders once they join the session. It is recommended that only the initial sender loading the content must call this RPC to reflect the user choice, and others shall adapt their sender UI accordingly. Upon a user interaction based caption setting any sender can call this RPC.

Method Name Arguments Definition
toggleCaption selectedCaption 2-letter language code for enabling caption among multiple captions or true when only one caption is available, or false to turn it off
availableCaptions Array of available captions' 2-letter language code 
{
    type: "rpc",
    content: {
        name: "toggleCaption",
        args: ["en", ["en", "es"]]
    }
}

Events

Receiver dispatches the events to the related sender SDK and receiver application in the format shown on the side:

{
   "name": EVENT_NAME,
   "time": TIME_STAMP,
   "info": EVENT_INFO,
   "args": [ ARG0, ARG1, ... ],
   "recipient": [SENDER0, SENDER1, ...]
}

Event information is provided below.

Event Name Event Definition Arguments
RECEIVER_TYPE_SET Chromecast player type has been set based on the content receiver type: “vod” or “live”
CHROMECAST_RECEIVER_ERROR Chromecast receiver has thrown an error error code
error info
Is Error Critical
VERIFICATION_STATUS Verification status has changed isVerified
token (if verified. o/w null)
METADATA_LOADED Video metadata is available event ID / video ID
upid (another identifier used as a key for metadata lookup) / video ID
metadata
video load configuration
PROGRAM_CHANGED Live program has changed event ID
upid (another identifier used as a key for metadata lookup)
metadata detail (rovi metadata if available)
SEEK_STARTED A sender initiated a seek none
SEEK_ENDED Sender initiated seek has been completed none
AD_BREAKS Ad breaks have been detected in the stream array of ad break info: {start: TS_SECONDS, end: TS_SECONDS}
RECOMMENDATIONS_AVAILABLE Detected recommended videos based on the current video recommendations object from MCP/TKX
RECOMMENDATIONS_VIEW_REQUESTED Recommendations view requested from connected players none
RECOMMENDATION_SELECTED A video from recommendations has been selected recommendation item object
CAPTION_STATUS Caption status has been updated selected caption
available captions
CHROMECAST_QUEUE_UPDATED Chromecast queue has been updated array of queue item objects: {queueIndex: QUEUE_INDEX, def_title: TITLE, def_description: DESCRIPTION, src_image_url: THUMBNAIL_IMAGE}
NEXT_VIDEO Next video metadata is available metadata
preload duration / countdown duration
CUSTOM_LOAD_CONFIG_DETECTED Custom config accompanying the main (encrypted load config detected) custom load config
PARTNER_DATA_UPDATED The merged custom load config and partner data set via setPartnerData has been updated data set by receiver app
PLAYING_START The playback has started content ID
VIDEO_STARTED The video started content ID
VIDEO_COMPLETED The video completed content ID
USER_PAUSE The video has been paused by a sender none
USER_RESUME The video has been resumed by a sender none
AD_STARTED The ad started content ID
AD_COMPLETED The ad completed content ID
CAPTION_STYLE_SET Caption style has been set by a sender (either while loading or after) caption style object

Errors

Error payload is passed with the args property as shown below. isCritical flag is used for providing the SDK user with the information about whether the playback will stop/not start at all or the error is recoverable.

{
    name: "CHROMECAST_RECEIVER_ERROR",
    time: {error time},
    info: "Chromecast receiver has thrown an error",
    args: [errorCode, errorDefinition, isCritical],
    recipient: [SENDER0, SENDER1, ...]
}
Error Code Error Definition isCritical
RCVR001 Failed to decrypt the sender verification payload true
RCVR002 Failed to parse the sender verification payload true
RCVR010 Failed to decrypt the sender payload true
RCVR011 Failed to parse the sender payload true
RCVR020 Custom message bus associated with the provided namespace does not exist while attempting to call sendCustomMessage false
RCVR021 Custom cast channel associated with the provided senderId does not exist while attempting to call sendCustomMessage false
RCVR030 The invoked remote method could not be located in the registered RPC methods false
RCVR300 Error related to media playback true
RCVR400 The requested media source could not be downloaded true
RCVR401 Error loading or parsing the manifest true
RCVR403 Error fetching the keys or decrypting the content true
RCVR405 Generic video service error true
RCVR900 Schedule service returned an expired event false

Samples

Sample Receiver Application

<!DOCTYPE html>
<html>
<head lang="en">
    <meta charset="UTF-8">
    <title></title>
    <link rel="stylesheet" href="partner.css"/>
    <script src="//www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
    <script src="//www.gstatic.com/cast/sdk/libs/mediaplayer/1.0.0/media_player.js"></script>
    <script data-view-url="partner.html" type="text/javascript" src="scripts/anvreceiver.min.js"></script>
    <script type="text/javascript" src="partner.js"></script>
</head>
<body>
</body>
</html>

Sample Partner Receiver Application script

anvr.config = {
    debug: false,
    videoPlaceholderId: "video-placeholder",
    customNamespaces: ["urn:x-cast:com.br.chromecast"]
};

//---------2. CALLBACK METHODS ------------
anvr.onReady = function() {
    // API methods from instantiated instances are exposed here
    var customMessageBus = anvr.getCustomMessageBus("urn:x-cast:com.br.chromecast");
    //...
};

anvr.onCustomMessage = function(namespace, sender, message) {
    anvr.sendCustomMessage(namespace, sender, message);
};

anvr.onStateChanged = function(state) {
     setTimeout(asyncTransition.bind(null, state), 100);// simulating async transition,
     // sync transition can be performed here by returning true
};

anvr.onTimeUpdated = function(currentTime, totalTime, contentType, adBreakIndex, adIndex) {
    //...
};

//--------- 3. ACRF EVENT LISTENER ------------
anvr.listener = function(event) {
// ..
    switch(event.name) {
        case "RECEIVER_TYPE_SET":
             //...
             break;
        case "METADATA_LOADED": // for initial metadata load (for vod and live)
             //..
             break;
        case "PROGRAM_CHANGED": // for live program change events
             //..
             break;
        case "SEEK_STARTED":
             //..
             break;
        case "SEEK_ENDED":
             //..
             break;
        case "AD_BREAKS":
             //..
             break;
    }
};

//---------- 4. HELPER METHODS ------------

function asyncTransition(state) {
     //..
     anvr.onStateTransitionCompleted();
}

//---------- 5. ACRF INIT CALL ------------
anvr.init();