Skip to main content

Chromecast

The guide shows how to integrate Chromecast with SmartLib in order to calculate metrics or handle ad tracking.

Following code samples use the actual player's API, you will need to adapt some part of the code you implemented in the previous step:

  • attach the player: create and attach the player instance
  • start a streaming session: get the final streaming URL and pass it to the player
  • stop a streaming session: stop the streaming session and the playback in case of user action or player error event

1. Overview​

The Google Cast SDK enables you to extend your Android, iOS, or Chrome app to direct its streaming video and audio to a TV or sound system. Your app becomes the remote control to play, pause, seek, rewind, stop, and otherwise control the media.

To have a SmartLib enabled app, you will have to create a custom receiver application (CAF).

A custom receiver application is an HTML5/JavaScript application that runs on the Chromecast, so the SmartLib for Chromecast has to be integrated. If you don't use the native player, you can also follow one of our SmartLib for web platforms.

The Chromecast is independent of the app sender, it means that a new session has to be created on the receiver.

2. Initialize SmartLib on Chromecast​

SmartLib has to be initialized with same parameters as the sender app:

  • analyticsAddress, nanoCDNHost, broadpeakDomainNames has to be sent to the Chromecast device to execute the right SmartLib initialization.
  • If a UUID, a session option, a device type, or any other customization has be set, it has to be sent to the Chromecast device and set through the right method.

In the sender app, forward the content url (non-redirected url) and all parameters:

const mediaInfo = new chrome.cast.media.MediaInfo(CONTENT_URL, ...);
const request = new chrome.cast.media.LoadRequest(mediaInfo);
request.customData = {
    analyticsAddress: ...,
    nanoCDNHost: ...,
    broadpeakDomainNames: ...,
    customData1: 'value1',
    customData2: 'value2'
};
await castSession.loadMedia(request);

In the receiver app, parse the customData object and apply the configuration

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
let session;

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
    ... 
    
    const data = loadRequestData.customData;
    
    SmartLib.getInstance().init(data.analyticsAddress, data.nanoCDNHost, data.broadpeakDomainNames);
    
    ...

    session = SmartLib.getInstance().createStreamingSession();
    session.setCustomParameter('customData1', data.customData1);
    session.setCustomParameter('customData2', data.customData1);
    
    ...
});

context.start();

3. Attach the player​

When creating the player instance, attach it to the current session.

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
    ...

    session = SmartLib.getInstance().createStreamingSession();
    
    ...
    
    // Attach your player to the current session
    session.attachPlayer(playerManager);
    
    ...
});

4. Start a streaming session​

The getURL method is used to get the actual streaming URL and start the streaming session. This method is also the starting point of the analytics calculation, for instance the startup time starts from this method.

The returned URL can be different for every video session. In case of using a Broadpeak CDN or a nanoCDN, it includes a unique token. It can be used only once per session object, once called the session is actually started.

When getURL returns an error, it means no streaming URL can be found. It has to trigger a specific behaviour on the application (error message, dialog...) and stopStreamingSession has to be called. Find more details about getURL errors on the session errors page.

It is recommended to perform this call on a different thread than the main thread, the method runs HTTP requests.

info

This method has to be called even for non-Broadpeak content URLs. In this case, the method will return the same URL.

info

Since the Chromecast is independent of the sender app, a new session has to be started. The getURL method has to call the original content URL (not the redirected URL).

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD, loadRequestData => {
    ...

    session = SmartLib.getInstance().createStreamingSession();

    ...
    
    session.attachPlayer(playerManager);
    
    ...

    // Get the stream URL from SmartLib
    return session.getURL(loadRequestData.media.contentId)
        .then(result => {
            if (!result.isError()) {
                loadRequestData.media.contentUrl = result.getURL();

                return loadRequestData;
            }
        });
});

5. Stop a streaming session​

The stopStreamingSession method must be called each time the session is stopped:

  • end users: when the playback is stopped by a user action
  • loading errors: when the streaming session cannot be started through the getURL method
  • player errors: when the player triggers a non-recoverable error during the playback (as a decoding error)
  • application or any others actions: when the app is killed
// Stop the session when playerManager is stopping the playback
session.stopStreamingSession();

If the player generates a non-recoverable error during the playback (as a decoding error), call stopStreamingSession to stop the session.

playerManager.addEventListener(types.ERROR, onErrorEvent);

function onErrorEvent(error) {
    session.stopStreamingSession();
}