Best Practices to Accurately Send State and Change Reports for Your Smart Home Skill
With Smart Home Skills, developers can enable proactive and predictive experiences to help customers save energy, save time and money, and feel more secure in their home. Features such as Hunches are one of the proactive experiences that lets Alexa change the state of a connected smart home device when it is not in its usual state. Saying “Alexa, goodnight” while the front door is unlocked? Alexa will lock it for you. Some of your home lights on at bedtime? Alexa will turn off the ones you don't usually leave on overnight. To take advantage of such experiences on behalf of your customers, you need to proactively report the state of endpoints. Accurate device states are the foundation of all ambient, proactive technology Alexa brings to customers.
For developers participating in the Works With Alexa program, proactively reporting endpoint states is mandatory to maintain the certification. Below are 12 recommendations to help you improve your accuracy score.
There are several steps that you need to take in order to send events: enable events, then implement the Alexa.Authorization interface, request permission to send events to the Alexa event gateway, and obtain authentication tokens for each customer. Finally, you will need to update your discovery response.
1. Enable Alexa Events in the Developer Console
To send reports to the Alexa event gateway, you must enable Alexa events in your skill. Once events are enabled, your skill will be able to share state information in your responses, and also proactively send state events. When you enable Alexa Events, your skill will have to go through a new certification cycle in order for the change to be effective.
To enable Alexa events, go to the Permissions tab in the Alexa Developer Console.
Smart Home skills:
Multi-capability skills:
Note both your Client Id and Client Secret in the permission tab, as you will need these values to request an access token for a customer.
To learn more: https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html
2. Enable Asynchronous Messages to be Sent to the Alexa Event Gateway
Alexa.Authorization interface is a critical piece, as it allows your skill to send asynchronous messages, such as change reports and state reports (if you chose to send state reports asynchronously), to the Alexa event gateway.
Once implemented, Alexa will send you an AcceptGrant directive every time a user goes through the account linking process.
If you have an existing skill and looking to enable proactive reporting, Alexa will also send you an AcceptGrant directive: there is a backfill process, during which you will receive an AcceptGrant directive for every customer that have previously enabled your skill. You must handle the AcceptGrant messages and go through the authentication process.
- Issues during backfilling process:
Should an issue arise and you lose access and refresh tokens associated with your customer(s), you will need to request new ones through an off-cycle backfill process. Amazon will repeat the process of resending AcceptGrant directives for each customer.
To learn more about the backfill process: https://developer.amazon.com/en-US/docs/alexa/smarthome/authenticate-a-customer-permissions.html#requesting-new-authorization-codes
To learn more about Alexa.Authorization Interface: https://developer.amazon.com/en-US/docs/alexa/device-apis/alexa-authorization.html
Most of controllers of the Smart Home API support State and Change reporting reporting excluding CameraStreamController which does not define any proactively reportable properties. For all other controllers, you must send State and Change reports for the controllers that you have implemented.
Each Smart Home device must implement EndpointHealth, which reports the connectivity of a device. See the rules about when to send a report in the following sections.
2. Update Your Discovery Response
Verify that all the capabilities that you have implemented support State and Change reporting.
You must indicate that you support State and Change reporting for each interface, in your discovery response. You indicate this by setting both retrievable and proactivelyReported to true. This is an important point as it affects our ability to deliver the best proactive experiences for your customers.
While a few endpoints cannot support State and Change reporting, such as infrared transmitters or low-energy devices, most devices should support state, and therefore should be set to both retrievable = true and proactivelyReported = true.
To learn more: https://developer.amazon.com/en-US/docs/alexa/smarthome/state-reporting-for-a-smart-home-skill.html
3. When to Send a Report
Below are the use cases describing when you need to send a report, and its type:
- When you detect a change, you send a ChangeReport
- When prompted about the state of a device, through a ReportState directive, you respond with a StateReport
- When Alexa sends a directive to change the state of a property, you respond with a Response, which contains the state of the device, and also send a ChangeReport. You may have to send multiple report types for the same event. For example, if Alexa sends you a directive to turn on a light, you respond with a Response, indicating that you handled the event successfully, with the new state. Then, you send a ChangeReport, with event cause as “VOICE_INTERACTION”.
To ensure that the state values you report are correctly processed, the following formatting rules must be observed:
- You must include an endpoint ID and a bearer token in each StateReport and ChangeReport:
- Each time you send an asynchronous response (including ChangeReport) on behalf of a customer, you include the customer’s access token (refresh token) in the scope object of the message to the Alexa event gateway.
- Send the endpoint ID within the endpoint object. Each endpoint ID must be unique: the endpoint ID sent in a given message must be identical to the one shared in the discovery response.
- Always report the current state of each interface in your StateReport. Do not simply send the value that has changed.
- A ChangeReport require a cause, which is the reason for a change. There are 5 possible values: voice or app interaction via Alexa, app interaction via your app, a physical interaction with the device, or a rule trigger. To learn more: https://developer.amazon.com/en-US/docs/alexa/smarthome/state-reporting-for-a-smart-home-`skill.html#cause-object
- Only report new events within the payload. There are 2 sections in which states can be reported in the change report:
- Context: report unchanged states
- Payload: report change(s) in state
For example: Developer LightBulb Inc. supports EndpointHealth and PowerController on their Smart Home Skill, which controls light bulbs. A customer possesses a light bulb from LightBulb Inc., which is connected to the Internet and controllable by Alexa.
At 10 am, the customer asks “Alexa, turn on the light." Developer LightBulb Inc. sends a ChangeReport with the following values:
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {
"path": "path/for/this/endpoint"
}
},
"payload": {
"change": {
"cause": {
"type": "VOICE_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "ON",
"timeOfSample": "2021-06-03T16:00:50Z",
"uncertaintyInMilliseconds": 60000
}
]
}
}
},
"context": {
"properties": [
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2021-06-03T16:00:50Z ",
"uncertaintyInMilliseconds": 0
}
]
}
}
The connectivity status did not change, however the bulb went from off to on.
State must be accurately reported, and rapidly sent.
1. Maintain a Low State Update Latency
ChangeReport events must be received within 3 seconds, from the instant a directive is sent to your Cloud to change the state of a device.
State must also be accurate, as a failure to report an event impacts the performances of proactive Smart Home features. When Alexa sends a ReportState directive about an endpoint, and you respond with a StateReport, Amazon will compare the value reported in the StateReport with the values you shared in the last ChangeReport (see accuracy score below).
A few recommendations to help you send events faster:
- Ensure that your fleet can communicate state updates back to your Cloud. You must be able to notice changes in your endpoints based on the 5 change causes enumerated above. You may implement polling mechanisms from your Cloud, in case your fleet cannot share frequent updates.
- ChangeReport are sent asynchronously to the Alexa event gateway, therefore you should consider latency best practices. Ensure that you are sending ChangeReport to the event endpoint that aligns with the geographic availability of your Smart Home skill (i.e., send the ChangeReport to the endpoint in the same region as your Lambda function, on behalf of customers for that region).
- Review the performance of your skill on the developer portal in the “Analytics” tab.
1. Maintain an Accuracy Above 98%
Alexa measures the accuracy of endpoint state by comparing values reported within the State reports to the last known property values reported to Alexa by the endpoint, either through proactive change reports, or by updated state from an Alexa directive. When Alexa receives a State Report, the values of the properties are compared to the property values that Alexa has for your endpoint. If all values are equal, the accuracy metric will be 100% per controller. A data mismatch will result in a lower percentage score.
2. Review Your Accuracy Score on the Developer Portal
On the developer console, select your live skill to access metrics. Under “Operational Metrics”, select “Change Report”. The page contains metrics for all the controllers for which we are receiving Change and State reports:
- Ensure that your 7-days average is on or above 98%, for each individual controller.
Below find common issues with State and Change reporting and solutions.
1. If your controller average is consistently below that baseline: you may be missing state updates events on your devices and not reporting them.
- Review the polling mechanisms and latency in sending messages to the Alexa event gateway.
2. If a controller chart does not appear in the Change Report dashboard: you may not be sending any state events
- Review the points listed above, as you may have missed a step in your implementation. Start with your discovery response. State and change reports will be ignored if the discovery response indicates that the endpoints does not support “proactivelyReported” and “retrievable.”
- Review the “Reporting State” tab as well, to ensure that you correctly respond to ReportState directives.
Now Available: Enable Alexa to Proactively Act on Hunches Without Customers Needing to Ask
Now Available: Enable Your Customers to Track and Manage their Devices’ Energy Usage with the Alexa Energy Dashboard
