Best Practices for the Alexa App
The Smart Home Skill API enables you to provide the most up-to-date information about the state a smart home device to Alexa, and that information is in turn provided to the customer in the Alexa app. This document contains best practices to support the Alexa app with your smart home skill.
- How smart home devices display in the Alexa app
- Skill best practices for the Alexa app
- Skill testing best practices for the Alexa app
- Related topics
How smart home devices display in the Alexa app
The Alexa app has two views for an individual smart home device: a settings page and a control page.
The setting page lists the type, description and name for a device. The control page shows the state of a device and enables a customer to control the device. For example, a customer could turn off a smart plug on the control page for the device. The following image shows an example settings page and control page for a smart plug.
A customer always sees the settings page for a smart home device, but a control page depends on the device category. The following table lists support for control pages in the app by display category:
|Display category in Discovery||Control page|
|LIGHT||Displays current state and enables on/off, brightness changes|
|SMARTLOCK||Displays current state, enables locking and customer-configured unlocking|
|SMARTPLUG||Displays current state and enables on/off and power level changes|
|SWITCH||Displays current state and enables on/off and power level changes|
|TEMPERATURE_SENSOR||Displays current state|
|THERMOSTAT||Displays current state and enables temperature changes|
Skill best practices for the Alexa app
To enable the best customer experience with the Alexa app, a smart home skill must do the following:
- Target payload version 3 in your skill, or upgrade your skill from version 2 to version 3. For details, see the Smart Home Skill Migration Guide.
- In device discovery, provide:
- A correct
displayCategory. The display category determines the Type displayed for the device in the Alexa app, the iconography used for it, the format of the control page for the device, and the device group it is included in. For example, the control page for a light would could display the current color and brightness levels.
descriptionfields for your devices. These attributes display in the Settings page for the device in the Alexa app. For details, see the endpoint object definition.
- As many fields as you can in the
additionalAttributesobject. Alexa uses these fields to identify duplicate devices and improve the user experience in the Alexa app.
- Accurate reporting on endpoint properties as retrievable and/or proactively reportable.
- A correct
- Implement EndpointHealth to report the health of your device.
- Respond to all directives in a timely manner with either the correct response or an error. For v3
Responseevents, include a
contextobject that reports the all the property values for an endpoint. This enables the app to stay in sync with the device state.
- Respond to ReportState directives with StateReport events, correctly reporting the state of all retrievable properties. This enables the app to stay in sync with the device state.
- Provide proactive state updates with ChangeReport events for all properties that are proactively reportable. This helps the app to stay in sync with the device state and alert the user if something changed.
Skill testing best practices for the Alexa app
Enable your skill with a test account and test the Alexa app experience for your skill.
- Make sure that devices associated with your account display in the Alexa app with the correct Type in the Alexa app, which affects the iconography and whether there is a control page for the device. If you see unexpected results, check the
DisplayCategoryyou specify for your device in discovery.
- On a control page for a device, make settings changes in the Alexa app, and see if the device state changes. Your skill should receive a directive indicating the request, which you would handle like a directive that originated from a voice request.
- Make setting changes with Alexa by using your voice, and then verify the state updates in the Alexa app.