Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
To enable Matter Casting in your apps update the following:
  • Client: This is your user-facing phone app for Android or iOS. By making your phone app a Matter client, the user can discover casting targets such as a Fire TV. They can also cast content, and control casting sessions.
  • Content app: This is your user-facing app on a Fire TV. By making your TV app a Matter content app, clients are able to control it. For example, they can start playback of specific content.
Communication between the client and player follows the Matter protocol. As a result, you can develop the client against a Fire TV device or use one of the sample players included in the Matter open source repository. This repository includes an Android player, which can run on Android TV. Similarly, the communication between the player and the content app is done using Matter-specific Android Intents, so that development can be done with a Fire TV device or with the Android player on a generic Android TV. The following explains how to integrate the Matter Casting SDK into your Android or iOS client app and how to interact with it.

Step 1: Integrate the Matter Casting SDK into your client app

Here are the steps required to integrate and initialize the Matter SDK into your mobile Android or iOS app.

Build and setup

To consume any of the APIs described in this document, your client must include the Matter Casting library in your Android or an iOS project.

Caching

Clients maintain an on-device cache with the information about the players it previously connected to. This cached information allows the client to connect with these players faster, and using fewer resources, by potentially skipping the longer commissioning process, and simply re-establishing the CASE session. This cache can be cleared by calling the ClearCache method on the client. Clearing the cache can be useful when the user signs out of the client, for instance.

Integration on Android

Download the Android SDK from the CSA Github repository and add it to your project. After it has been added to your project, initialize the library with the following steps (full listing).

1. Define the rotating device identifier

This is a unique per-device identifier, consisting of a randomly-generated 128-bit or longer octet string. Review the Matter specifications for details on how to generate the Rotating Device Identifier. Instantiate a DataProvider object as described below to provide this identifier.

2. Initialize commissioning data

The CommissionableDataProvider object contains the passcode and other artifacts, which identify the client and are provided to the player during the commissioning process. Refer to Matter specification’s Onboarding Payload section for details on commissioning data.

3. Add Device Attestation Credentials

The Device Attestation Credentials (DAC) object provides the certificates required to sign messages as part of the Device Attestation process during commissioning. The Matter specification provides background information on how this works. For development purposes, you can use the DAC provided in the sample code. Define dacProvider to provide the client’s Device Attestation Credentials, by implementing com.matter.casting.support.DACProvider.

4. Initialize the client

After the objects are created, initialize the client as listed below. The client might be initialized only one time before a Matter Casting session is started.

Integration on iOS

A. Build the Matter framework The open source Github repository provides a framework for handling low-level communication between your iOS client and the video casting player and content app. Build the framework using the following steps.
  • Git clone the Github repository to your development machine using git clone https://github.com/project-chip/connectedhomeip/tree/master
  • In a terminal, change the folder to the location of your repository and run source scripts/bootstrap.sh. This builds the libraries and associations required.
  • Open the example iOS app to build the framework locally.
  • Include the framework in your iOS app.
B. Integrating the Matter Casting framework into your app

1. Define the rotating device identifier

This is a unique per-device identifier that consists of a randomly-generated 128-bit or longer octet string. Review the Matter specifications for details on how to generate the Rotating Device Identifier. Instantiate a DataProvider object as described below to provide this identifier.

2. Initialize commissioning data

This object contains the passcode and discriminator. which identifies the app and provides the CastingPlayer object during the commissioning process. A passcode must be included as a 27-bit unsigned integer. This serves as proof of possession during commissioning. A Discriminator must be included as a 12-bit unsigned integer, which must match the value that a device advertises during commissioning. See Chapter 5 Commissioning in the Matter Core specification for more details on the Matter specification’s Onboarding Payload section. Add func CommissionableDataProvider to the MCAppParametersDataSource class previously defined, that provides the required values to MCCastingApp. If using the CastingPlayer / Commissioner-Generated Passcode UDC feature, the casting client must update the CommissionableDataProvider during the VerifyOrEstablishConnection() API call (described later). In the following example, the update function updates the CommissionableData with a CastingPlayer generated passcode entered by the user on the casting client UX.

3. Add device attestation credentials

This object contains the DeviceAttestationCertificate and ProductAttestationIntermediateCertificate, that implements a way to sign messages when called by the Matter TV Casting library as part of the Matter Device Attestation process during commissioning. Add functions castingAppDidReceiveRequestForDeviceAttestationCredentials and didReceiveRequestToSignCertificateRequest to the MCAppParametersDataSource class previously defined, which returns MCDeviceAttestationCredentials and sign messages for the Casting client.

4. Initialize SDK

After you have created the previous DataProvider objects, you are ready to initialize the casting app as described below. Call MCCastingApp.initialize with an object of MCAppParametersDataSource.
After initialization, call start and stop on the MCCastingApp shared instance when the app sends UIApplication.didBecomeActiveNotification and UIApplication.willResignActiveNotification.

Step 2. Integrate Matter with your Fire TV app

After Integrate the Matter Casting SDK into your client app, your client is ready to discover players and content apps on the same Matter network. Before you can listen, send, and receive Matter commands from the content app on Fire TV you must integrate it with the Fire TV Matter Casting service. This step shows you how to use the Android TV example app to bootstrap a content app for Android TV that’s already Matter Casting-enabled.

1. Update your Android manifest

Enabling Matter Casting requires extending the information provided in your Android manifest. The player and the Matter agent client use information provided in the Android manifest to understand which clients to allow casting to your content app and which Matter clusters the content app supports.

1. Product and vendor information

Update your app’s tag to include your product ID and vendor ID. See App Attestation for more information. For development, you have the option to use the Product ID of 65521, Vendor ID of 32769, and Vendor Name provided in the following example.

2. Update permissions

To bind with the player’s Matter agent service, your content app must provide the following permissions in its manifest file.
The permission string is defined within the common-api module as PERMISSION_MATTER_AGENT_BIND. AndroidManifest.xml can be used as a reference point.

3. Supported clusters

Next, to add the Clusters your content app supports, add the following to the Android manifest.
Now, create the JSON file static_matter_clusters that holds the list of clusters supported by your content app.

2. Integrate with Matter AIDL files

Matter Casting uses the Android Interface Definition Language (AIDL) to define the programming interface to communicate between the player and your content app. Copy the following three AIDL files from the example app to your app’s repository: IMatterapplicationAgent.aidl, SetSupportedClustersRequest.aidl, and SupportedCluster.aidl. This helps you integrate with the following required methods setSupportedClusters and reportAttributeChange. These methods are necessary for the following:
  • setSupportedClusters
    • This method reports clusters dynamically to the Matter agent.
    • This is not incremental and on each call, report the full set of clusters. Any clusters that are omitted in the latest method call that were added previously are removed.
    • The previous behavior does not impact static clusters declared in app resources and they are not removed.
    • Dynamic cluster can be used to override and hide a static cluster based on the cluster name.
  • reportAttributeChange
    • This method reports changes to attributes by the content app.
    • It also takes in the cluster ID and attribute ID for the reported attribute change.
Additional documentation can be found in the Matter TV app common-api.

3. Create a Matter agent client

Create a Matter agent client as found in the example. The agent is used to connect to the Matter service and to use the methods provided in the previous AIDL step. Here’s an example of establishing a binder connection.

4. Register the Matter command receiver

The content app registers itself as a receiver to handle incoming Matter commands. To receive commands sent from the client, the content app registers a receiver instance that listens for MATTER_COMMAND intents with permission.
To send data and respond to commands, include the permission com.matter.tv.app.api.permission.SEND_DATA for the receiver as previously seen. After you receive the intent, you can read the Matter command in your content app.
Use this class to map command and cluster IDs.

5. Execute commands

After the content app is started, it binds to the Matter agent service to receive commands and registers all its dynamic endpoints and supported clusters through the reportClusters call.
If the content app needs to report an attribute change, use reportAttributeChange on the Matter agent to notify the SDK. When receiving a command from the Matter SDK, an intent of type ACTION_MATTER_COMMAND is received using BroadcastReceiver implemented by the content app. The intent includes the command ID, cluster ID, and corresponding payload data. After the command handler is called, a response for these commands must be sent. An example receiver is found in MatterCommandReceiver.java. All the internal fields within the intents are found under MatterIntentConstants provided through the common-api module.

6. Install your Fire TV app on-demand

The following assumes that the customer has your content app installed and they are casting to it. However, this might not be the case. If the content app is not installed, Fire TV can prompt them to install the app if its package name is provided in the ApplicationID information of the launch app cluster payload.

Step 3. Interact with players

In this step you learn how to discover, select, and connect to a player, issue commands, read attributes like playback state, and subscribe to playback events.

Interaction on Android

1. Discover casting players

The client discovers players such as Fire TV using Matter Commissioner Discovery over DNS-SD by listening for player events as they are discovered, updated, or lost from the network. First implement CastingPlayerDiscovery.CastingPlayerChangeListener.
Then register these listeners and start discovery. Add castingPlayerChangeListener as a listener to MatterCastingPlayerDiscovery to listen to changes in the discovered players and call startDiscovery.
Connect with a player to see the list of endpoints they support. Refer to the Connection section for details on how to discover available endpoints supported by a casting player.

2. Connect with a discovered player

Each player object created during Discovery contains information such as deviceName, vendorId, and productId, which helps the user pick the right player. A client can attempt to connect to selectedCastingPlayer using Matter User Directed Commissioning (UDC). The Matter TV Casting library locally caches information required to reconnect to a player object after the client has been commissioned by it. After that, the Casting client is able to skip the full UDC process by establishing CASE with the player directly. After connected, the Player object contains the list of available endpoints on that player. The following arguments might also be passed in as options. commissioningWindowTimeoutSec indicates how long to keep the commissioning window open, if commissioning is required. DesiredEndpointFilter specifies the attributes, such as vendor ID and product ID, of the endpoint the client wants to interact with after connecting. This forces the Matter TV Casting library to go through the full UDC process in search of the desired endpoint, in cases where it’s not available in the client’s cache. The client might call verifyOrEstablishConnection on the CastingPlayer object it wants to connect to.

3. Select an endpoint on the player

On a successful connection with a player object, a casting client might select one of the endpoints to interact with based on its attributes, such as the vendor ID, product ID, or list of supported clusters. In the context of Matter Casting, endpoints refer to your content app.

4. Interacting with a casting endpoint

After the Casting client has selected an endpoint, it is ready to issue commands to it, read the current playback state, and subscribe to playback events. The list of supported clusters, commands, and attributes on Android can be found in the example code. Issuing commands Given the endpoint from the previous step, you can send a LaunchURL command (part of the Content Launcher cluster) by calling the launchURL method on a ChipClusters.ContentLauncherCluster object.
Read operations and subscriptions The following demonstrates how to read data from your content app and update the client user interface to represent the current playback position. In this example the customer subscribes by calling subscribeCurrentStateAttribute on a ChipClusters.MediaPlaybackCluster object.

Interaction on iOS

1. Discover casting players

Now that you have integrated the Matter library into your client and in the content app, you can discover and communicate with video casting players and content apps on the same Matter fabric. Implement func addDiscoveredCastingPlayers, func removeDiscoveredCastingPlayers and func updateDiscoveredCastingPlayers, which listens to notifications as casting players are added, removed, or updated.
Register these listeners to start discovery by calling addObserver in NotificationCenter with the appropriate selector, and then call start on the sharedInstance object of MCCastingPlayerDiscovery.

2. Connect to a casting player

Each CastingPlayer object created during discovery contains information such as deviceName, vendorId, and productId, which helps the user pick the right CastingPlayer. A Casting client can attempt to connect to selectedCastingPlayer using Matter User Directed Commissioning (UDC). The Matter TV Casting library locally caches information required to reconnect to a CastingPlayer object after the Casting client has been commissioned by it. After that, the Casting client can skip the full UDC process by establishing CASE with the CastingPlayer object directly. After connected, the CastingPlayer object contains the list of available endpoints on that CastingPlayer object. commissioningWindowTimeoutSec indicates how long to keep the commissioning window open, if it’s required. DesiredEndpointFilter specifies the attributes, such as the vendor ID and product ID of the endpoint the Casting client wants to interact with after connecting. This forces the Matter TV Casting library to go through the full UDC process in search of the desired endpoint, in cases where it’s not available in the casting client’s cache. The Casting client might call verifyOrEstablishConnection on the MCCastingPlayer object it wants to connect to and handle any errors through NSErrors that might happen in the process.

3. Select a casting player endpoint

After successfully connected with a CastingPlayer object, a casting client might select one of the endpoints to interact with based on its attributes (such as vendor ID, product ID, or list of supported clusters). Select MCEndpoint as shown below.

4. Interacting with a casting endpoint

After the casting client has selected an endpoint, it is ready to issue commands to it, read current playback state, and subscribe to playback events. Refer to the following operating system-specific files to find the list of clusters, commands, and attributes with their request and response types available for use with the Matter TV casting library. Refer to the following files:

5. Issuing commands

Given an endpoint (MCEndpoint), it can send a LaunchURL command, which is part of the Content Launcher cluster, by calling the invoke method on MCContentLauncherClusterLaunchURLCommand.

6. Read operations

CastingClient might read an attribute from the endpoint on the CastingPlayer object. It should make sure that the desired cluster and attribute are available for reading on the endpoint before trying to read it. Within MCEndpoint, the VendorID can be read similarly, by calling the read method on MCApplicationBasicClusterVendorIDAttribute.
Last modified on March 26, 2026