Alexa.ApplicationStateReporter Interface 1.0


Implement the Alexa.ApplicationStateReporter interface to notify Alexa when an app, such as Prime Video, is open on the endpoint. Alexa uses the information to serve subsequent customer utterances.

For the list of languages that the Alexa.ApplicationStateReporter interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.ApplicationStateReporter interface doesn't have any user utterances.

Dependencies

If your endpoint supports Alexa.ApplicationStateReporter, the endpoint must also support Alexa 3.0 and Alexa.Discovery 3.0 or higher.

Reportable properties

The Alexa.ApplicationStateReporter interface uses the foregroundApplication property as the primary property. You identify that you support the property in your discovery response. Use ChangeReport to report a change in the visibility of the app.

Property Description Type

id

Unique ID for this app on the endpoint.
Valid values: Launch Target app ID.

String

version

Version of the app.

String

type

Customizable app type.
Valid values: android, vsk.

String

metadata

Describes the visibility of the app.

Object

metadata.category

List of categories to which the app belongs.
Valid values: LAUNCHER, OTHER.

Array of string

metadata.isVisible

Set to true when the app is open on the endpoint. Set to false when the app is closed or not visible.
For example, a window overlay fully obstructing the app, a device screensaver, or a device gone to sleep might impact visibility.

Boolean

Capability assertion

You describe endpoints that support Alexa.ApplicationStateReporter using the standard discovery mechanism described in Alexa.Discovery. You include the Alexa.ApplicationStateReporter in the capabilities list for each endpoint.

Use ALEXA_VOICE_ENABLED for the display category. For the full list of display categories, see display categories.

Discover response example

The following example shows Discover.Response message for a device that supports the Alexa.ApplicationStateReporter and Alexa.EndpointHealth interfaces.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "manufacturerName": "Manufacturer name of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer name of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ApplicationStateReporter",
                        "version": "1.0",
                        "properties": {
                            "supported": [{
                                    "name": "foregroundApplication"
                                }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

AddOrUpdateReport example

The following example shows an AddOrUpdateReport event for a device that supports the Alexa.ApplicationStateReporter and Alexa.EndpointHealth interfaces.

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "AddOrUpdateReport",
            "payloadVersion": "3",
            "messageId": "Unique identifier, preferably a version 4 UUID"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpoints": [{
                "endpointId": "Unique ID of the endpoint",
                "registration": {
                    "productId": "productID-001",
                    "deviceSerialNumber": "serial-001"
                },
                "manufacturerName": "Manufacturer name of the endpoint",
                "description": "Description to be shown in the Alexa app",
                "friendlyName": "Living Room TV",
                "displayCategories": ["TV"],
                "additionalAttributes": {
                    "manufacturer": "Manufacturer name of the endpoint",
                    "model": "Model of the device",
                    "serialNumber": "Serial number of the device",
                    "firmwareVersion": "Firmware version of the device",
                    "softwareVersion": "Software version of the device",
                    "customIdentifier": "Optional custom identifier for the device"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ApplicationStateReporter",
                        "version": "1.0",
                        "properties": {
                            "supported": [{
                                "name": "foregroundApplication"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

Directives

The Alexa.ApplicationStateReporter interface doesn't define any directives. Use Alexa.ChangeReport to report the visibility of the foreground app.

State reporting

Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all the retrievable properties in the context object. You identify your retrievable properties in your capability assertion. For details about state reports, see Understand State and Change Reporting.

StateReport response example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "StateReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "correlationToken": "an opaque correlation token that matches the request",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint ID"
        },
        "payload": {}
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ApplicationStateReporter",
                "name": "foregroundApplication",
                "value": {
                    "id": "amzn1.alexa-ask-target.app.36377",
                    "version": "2019020342",
                    "type": "vsk",
                    "metadata": {
                        "categories": [
                            "LAUNCHER"
                        ],
                        "isVisible": false
                    },
                    "timeOfSample": "2023-04-03T16:20:50.52Z",
                    "uncertaintyInMilliseconds": 0
                }
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2023-04-03T16:20:50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

Change reporting

You send an Alexa.ChangeReport event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.

Use Alexa.ChangeReport to report that the specified app is visible or not visible on the endpoint.

ChangeReport event example

Copied to clipboard.

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "ChangeReport",
            "messageId": "a unique identifier, preferably a version 4 UUID",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "an OAuth2 bearer token"
            },
            "endpointId": "endpoint ID"
        },
        "payload": {
            "change": {
                "cause": {
                    "type": "PHYSICAL_INTERACTION"
                },
                "properties": [{
                    "namespace": "Alexa.ApplicationStateReporter",
                    "name": "foregroundApplication",
                    "value": {
                        "id": "amzn1.alexa-ask-target.app.36377",
                        "version": "2019020342",
                        "type": "vsk",
                        "metadata": {
                            "categories": [
                                "LAUNCHER"
                            ],
                            "isVisible": true
                        },
                        "timeOfSample": "2023-04-03T16:20:50.52Z",
                        "uncertaintyInMilliseconds": 0
                    }
                }]
            }
        },
        "context": {
            "properties": [{
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2023-04-03T16:20:50Z",
                "uncertaintyInMilliseconds": 0
            }]
        }
    }
}

Was this page helpful?

Last updated: Nov 27, 2023