examples/tv-app/android/App/common-api/README.md

# Matter tv app common-api

The tv-app common-api module defines the interface to interact with the Matter
agent service for the content apps. This module defines the AIDL interfaces,
clusters and command abstractions accessible. It also defines various constants
and intent field definitions that would be used by the content app while
interacting with the Matter SDK. The interface provided by this module helps
content app to register dynamic endpoints as well as report any attribute
changes to the SDK.

## Permissions needed

To utilize the Matter agent interface the partner apps need to

-   Query and bind themselves to a service that handles
    `com.matter.tv.app.api.action.MatterAppAgent` action
-   The host process should hold the
    `com.matter.tv.app.api.permission.SEND_DATA` permission
-   To bind with the Matter app agent service, the client should hold the
    `com.matter.tv.app.api.permission.BIND_SERVICE_PERMISSION` permission

## Matter app agent APIs

The Matter app agent service exposes the following interface

-   `setSupportedClusters`
    -   This API allows partners to report clusters dynamically to the Matter
        agent
    -   This API is not incremental and on each API call we should report the
        full set of clusters - any clusters that are omitted in the latest API
        call that were added previously will be removed
    -   The above behavior does not impact static clusters declared in app
        resources and they will not be removed
    -   Dynamic cluster can be used to override and hide a static cluster based
        on cluster name
-   `reportAttributeChange`
    -   This API allows reporting changes to attributes by the content app
    -   It takes in the cluster ID and attribute ID for which the attribute
        change is reported

## Cluster and Attribute IDs

The common API package defines commonly used cluster IDs as well as
corresponding Attribute ID's through `com.matter.tv.app.api.Clusters`. The
common-api provides a quick way to refer to different clusters defined by the
Matter spec relevant for media casting, as well as attributes and commands
associated with each one.

## Intents

The supported intents are defined under the
`com.matter.tv.app.api.MatterIntentConstants`. This helper class defines the
relevant intents used while interacting with the Matter app agent service. This
includes the android permission strings to as well as command and attribute
intent fields to be used.