Best Practices for the Alexa App

The Smart Home Skill API enables you to provide the most up-to-date information on 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 you smart home skill.

How smart home devices display in the Alexa App

The Alexa app has two views for an individual smart home device; a settings page that lists the type, description and name for a device, and a control page that 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
ACTIVITY_TRIGGER None
CAMERA None
LIGHT Displays current state and enables on/off, brightness changes
OTHER None
SMARTLOCK Displays current state, enables locking and customer-configured unlocking
SMARTPLUG Displays current state and enables on/off and power level changes
SPEAKER None
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
TV None

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. If you cannot update your skill at this time, see App support for v2
  • 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.
    • Accurate manufacturerName and description fields for your devices. These will display in the Settings page for the device in the Alexa app.
    • Accurate reporting on endpoint properties as retrievable and/or proactively reportable.
  • Respond to all directives in a timely manner with either the correct response or an error. For v3 Response events, include a context that reports the all of 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.

For more information on implementing StateReport and ChangeReport events, see State Reporting in a Smart Home Skill and Send Events to the Alexa Event Gateway.

Skill testing best practices for the Alexa App

Enable your skill with a test account and test the Alexa app experience for your skill.

For example:

  • Check 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 are seeing unexpected results, check the DisplayCategory you 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 Lambda function 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 using your voice, and check for the state updates in the Alexa app.

Smart Home Skill API v2

The Alexa app support for skills that target payload version 2 is limited. A customer can make settings changes, but the app may not show the current state of a device because v2 enables device query for thermostats and locks only.

For the best experience for v2 skills, provide the correct applianceType, and accurate friendlyDescription and manufacturerName in device discovery. This enables the app to display the correct control page and iconography, where applicable.

Test your skill with the Alexa app like described in the testing section.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment