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 |
|---|---|---|
|
|
Unique ID for this app on the endpoint. |
String |
|
|
Version of the app. |
String |
|
|
Customizable app type. |
String |
|
|
Describes the visibility of the app. |
Object |
|
|
List of categories to which the app belongs. |
Array of string |
|
|
Set to |
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.
{
"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.
{
"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
{
"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
{
"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
}]
}
}
}
Related topics
Last updated: Apr 11, 2023