Best Practices for the Alexa App

The Smart Home Skill API enables you to provide the most up-to-date information about the state of a smart home device to Alexa. That information is, in turn, provided to the customer in the Alexa app. Follow the best practices to support the Alexa app with your smart home skill.

How smart home devices display in the Alexa app

Customers can view an individual smart home device in the Alexa app on the settings page or the control page. The settings page lists the type, description, and name for a device. Here, a customer can change the name of the device, change the device type, or disable a device that they no longer use. The control page shows the state of a device and enables a customer to control the device. For example, a customer can turn off a smart plug on the control page for the device.

Customers can always see the settings page for a smart home device, but their ability to see a control page depends on the device category. The following table shows example support for control pages in the Alexa app by display category.

Display category in Discovery Control page

ACTIVITY_TRIGGER

None

CAMERA

None

LIGHT

Displays current state and enables on/off and brightness changes

OTHER

None

SMARTLOCK

Displays current state and 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 perform the following actions:

  • Target payload version 3 in your skill, or upgrade your skill from version 2 to version 3.
    For details about how to update your version 2 skill, see the Smart Home Skill Migration Guide.
  • In your discovery response, provide the following information:
    • 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's included in. For example, the control page for a light might display the current color and brightness levels.
    • Accurate manufacturerName and description fields 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 additionalAttributes object. 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.
  • Implement EndpointHealth to report the health of your device. Support as many EndpointHealth properties as you can.
  • Respond to all directives in a timely manner with either the correct response or an error. For v3 Response events, include a context object that reports all the property values for an endpoint. This enables the app to stay in sync with the device state.
  • To report linked endpoints to Alexa so that the Alexa app displays the devices together, include the Relationships object in your discovery response and proactive update events. For details, see Identify relationships between endpoints.
  • Respond to ReportState directives with StateReport events and correctly report 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 details about StateReport and ChangeReport events, see State Reporting in a Smart Home Skill and Send Events to the Alexa Event Gateway.

Best practices for testing the device in the Alexa app

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

Verify the following items in the Alexa app:

  • Make sure that devices associated with your account display in the Alexa app with the correct Type. The type affects the iconography and whether there is a control page for the device. If you see unexpected results, check the DisplayCategory that you specified for your device in the discovery response.
  • On the control page for a device, make a change, and then verify that the device state changes. After you change the device in the Alexa app, Alexa sends your skill a directive with the requested change. Verify that your skill handles the directive in the same manner as it handles a directive that originates from a voice request.
  • Ask Alexa to make changes to your device by using your voice, and then verify the state updates in the Alexa app.

Last updated: Mar 16, 2023