Add Core Features to Your Custom Web Receiver

Page Summary

This page describes the features and code snippets available for a Custom Web Receiver app.
Key features include the cast-media-player element for built-in UI, custom styling, loading the Web Receiver framework, handling messages and events, queueing for autoplay, and options for configuration and supported commands.
The CastReceiverContext manages the SDK initialization and configuration through CastReceiverOptions, while PlaybackConfig allows configuring playback variables like DRM information and request handlers.
Web Receiver apps can handle player events using event listeners and intercept messages to execute custom code and modify request data.
MediaInformation properties like entity, contentUrl, and contentId are used for loading media in the LOAD message.
The Web Receiver SDK supports handling user interaction from various sources, managing user action states, and processing voice commands and stream transfers.

This page contains code snippets and descriptions of the features available for a Custom Web Receiver app.

A cast-media-player element that represents the built-in player UI provided with Web Receiver.
Custom CSS-like styling for the cast-media-player element to style various UI elements such as the background-image, splash-image, and font-family.
A script element to load the Web Receiver framework.
JavaScript code to intercepting messages and handling events.
Queue for autoplay.
Options to configure playback.
Options to set the Web Receiver context.
Options to set commands which are supported by the Web Receiver app.
A JavaScript call to start the Web Receiver application.

Application configuration and options

Configure the application

The CastReceiverContext is the outermost class exposed to the developer, and it manages loading of underlying libraries and handles initialization of the Web Receiver SDK. The SDK provides APIs that allow application developers to configure the SDK through CastReceiverOptions. These configurations are evaluated once per application launch and are passed to the SDK when setting the optional parameter in the call to start.

The example below shows how to override the default behavior for detecting if a sender connection is still actively connected. When the Web Receiver has not been able to communicate with a sender for maxInactivity seconds, a SENDER_DISCONNECTED event is dispatched. The configuration below overrides this timeout. This can be useful when debugging issues as it prevents the Web Receiver app from closing the Chrome Remote Debugger session when there are zero connected senders in an IDLE state.

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

Configure the player

When loading content, the Web Receiver SDK provides a way to configure playback variables such as DRM information, retry configurations, and request handlers using cast.framework.PlaybackConfig. This information is handled by PlayerManager and is evaluated at the time that the players are created. Players are created each time a new load is passed to the Web Receiver SDK. Modifications to the PlaybackConfig after the player has been created are evaluated in the next content load. The SDK provides the following methods for modifying the PlaybackConfig.

CastReceiverOptions.playbackConfig to override the default configuration options when initializing the CastReceiverContext.
PlayerManager.getPlaybackConfig() to obtain the current configuration.
PlayerManager.setPlaybackConfig() to override the current configuration. This setting is applied to all subsequent loads or until it is overridden again.
PlayerManager.setMediaPlaybackInfoHandler() to apply additional configurations only for the media item being loaded on top of the current configurations. The handler is called just before player creation. Changes made here are not permanent and aren't included in queries to getPlaybackConfig(). When the next media item is loaded, this handler is called again.

The example below shows how to set the PlaybackConfig when initializing the CastReceiverContext. The configuration overrides outgoing requests for obtaining manifests. The handler specifies that CORS Access-Control requests should be made using credentials such as cookies or authorization headers.

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

The example below shows how to override the PlaybackConfig using the getter and setter provided in PlayerManager. The setting configures the player to resume content playback after 1 segment has been loaded.

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

The example below shows how to override the PlaybackConfig for a specific load request using the media playback info handler. The handler calls an application implemented method getLicenseUrlForMedia to obtain the licenseUrl from the current item's contentId.

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

Event listener

The Web Receiver SDK allows your Web Receiver app to handle player events. The event listener takes a cast.framework.events.EventType parameter (or an array of these parameters) that specifies the event(s) that should trigger the listener. Preconfigured arrays of cast.framework.events.EventType that are useful for debugging can be found in cast.framework.events.category. The event parameter provides additional information about the event.

For example, if you want to know when a mediaStatus change is being broadcasted, you can use the following logic to handle the event:

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

Message interception

The Web Receiver SDK allows your Web Receiver app to intercept messages and execute custom code on those messages. The message interceptor takes a cast.framework.messages.MessageType parameter that specifies what type of message should be intercepted.

The interceptor should return the modified request or a Promise that resolves with the modified request value. Returning null will prevent calling the default message handler. See Loading media for more details.

For example, if you want to change the load request data, you can use the following logic to intercept and modify it:

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity)