Create a Basic CAF Receiver App

Jump start - The code for creating a basic receiver is simple. Skip ahead to register your receiver app, then create a basic receiver app.

Cast Application Framework Receiver SDK is a major upgrade from the current Receiver v2 SDK. Improvements focus on significantly reducing the amount of code it takes to implement a receiver app, while making Cast more reliable to maintain. This was done by implementing all common use cases into the new Cast Application Framework (CAF).

CAF Receiver SDK also comes with a built-in media player, which provide a seamless and easy playback experience. Moving forward, more features will be added that automatically work on CAF Sender and CAF Receiver, including an updated queuing implementation, ads support, preload and others. It will also provide out-of-box support for Google Assistant. CAF will dramatically reduce your implementation effort and time to market of new features.

With all the simplifications and improvements, CAF Receiver SDK still provides the same flexibility as before, allowing your own player UI, intercepting and overriding messages and methods to execute custom business logic.

Compatibility with senders: A receiver app implemented with the CAF receiver SDK works best with CAF senders; it is also compatible and works well with v2 senders.

Note about CAF: The term "CAF Receiver SDK" refers to the Receiver SDK that incorporates the Cast Application Framework (which was not available in previous releases).

Google CAF Receiver SDK

Your receiver app accesses the CAF Receiver API with the following reference:

<script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>

Do not self-host the cast_receiver_framework.js resource. Updates will be applied periodically to address bug fixes and new features. Self-hosting can break your receiver app by preventing bug fixes from being applied, including proactive changes that address advancements in firmware.

Best practice for URL protocols: Notice the URL above does not specify an "http:" or "https:" protocol. Omitting these protocols when sourcing the cast_receiver_framework.js resource enables this resource to be fetched using the same protocol as the server hosting the receiver application. This means that switching between HTTP for development and HTTPS for production is transparent and will not require a code change. (Receiver apps should be hosted on TLS-capable servers.)

Application life cycle

The receiver application life cycle starts from the point at which the receiver is loaded onto the Cast device and proceeds to the point at which the application is torn down and the Cast device reverts back to its default state.

Over the life cycle of a receiver application, messages are exchanged between the receiver and any connected sender applications. A sender application will send an initial message to a Google Cast device requesting a session be created using a specific app ID. This kicks off the life cycle of the receiver, as the Google Cast device will attempt to load the receiver application. Assuming there are no network issues, the receiver application will be downloaded from the network using the resolved URL associated with the app ID. Once loaded, the receiver application will perform its setup operations and indicate that it is ready to process messages from any connected sender applications.

A receiver application may tear down (end its current life cycle and close the application) under the following conditions:

  • The receiver application gets an explicit message from the last connected sender to end the application session.
  • The receiver application has been idle for a defined period of time without any connected senders and decides to end the application session.
  • A different cast session was started.
  • The receiver encounters a fatal error during its normal life cycle.

CAF Receiver SDK handles all common cases in accordance with our UX guidelines.

Major classes

The CAF receiver SDK framework has 2 major classes:

  • cast.framework.CastReceiverContext - Manages overall framework and loads any necessary libraries. With this object, you can:

    • Set application configuration options
    • Handle system events (such as sender connected or disconnected)
    • Create custom channels
    • Initiate cast communication
  • cast.framework.PlayerManager - Manages media playback. It handles the underlying player and media element according to the request from the sender. With this object, you can:

    • Handle playback operations
    • Handle playback-related requests from sender
    • Handle playback-related events

Register your receiver app

Before developing a receiver application, you will need to register your receiver app with the Google Cast SDK Developer Console. See Registration for more information. All receiver applications require sender applications to provide an app ID with the command messages they send to the receiver through the sender API. When you register your receiver application, you will receive the app ID to include in your sender's API calls.

Create a basic receiver app

The following is the main structure of a basic CAF receiver app, which has no customization:

  1. A cast-media-player element to represent the media player.
  2. A script element to load the Cast receiver framework.
  3. Call start() to start the receiver application with no options.

Here is the minimum code for a receiver application using the Cast Application Framework without any customization. You can copy and paste this script exactly as-is into your app to create the receiver app.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    cast.framework.CastReceiverContext.getInstance().start();
  </script>
</body>
</html>

At this point, a user can open their sender app, connect to their Cast device, then navigate to media and press Play, which tells the receiver to stream the media to the TV for the user to watch..

Compare this basic receiver with a customized receiver app.

Media and players

The Cast framework provides a built-in media player, represented by the cast-media-player element. This media player supports playback for streaming protocols such as MPEG-DASH, HLS, and Smooth Streaming.

A set of supported media codecs and containers are listed at Supported Media. Through Cast messaging, developers can support a list of sender-initiated operations such as load, play, pause and seek, where CAF handles the interactions with the media. For a list of supported operations, refer to the sender API reference for your app's platform: RemoteMediaClient in Android Sender, GCKMediaControlChannel in iOS Sender and Media in Chrome Sender.

Cross-Origin Resource Sharing

Google Cast fully supports Cross-Origin Resource Sharing (CORS). Streaming protocols, unlike most file-based protocols, access content in an asynchronous way using XMLHttpRequest. In a CORS world, these requests are guarded against inappropriate access by the CORS header from the server where the resource originates. This means that your content's server has a say on where it may be included. Most modern browsers fully support CORS. iOS and Android devices access the content at a lower level and do not look at these headers. This is often the first issue that comes up when a developer wishes to use streaming content. See Cross-Origin Resource Sharing for details.

Next Step

Go to Add features to your receiver app.