AMA Kit Setup Flow

This page describes the setup flow for a device implementing the AMA Kit to help you understand the setup process that your device users go through when they pair their AMA-enabled accessory with the Alexa app:

Set up deep links within your accessory companion app

To help your users set up their AMA-enabled devices, provide the following deep links through the accessory companion app:

  • Alexa app installation deep link – A deep link launched within the companion app setup flow to prompt first-time Alexa users to download and install the Alexa app from the appropriate app store, if they haven't already done so.
  • Alexa Devices deep link – A deep link to the Alexa Devices screen, which helps users add the new AMA-enabled device to their list of recognized Alexa devices in the Alexa app. Use the following formats to configure your deep links:

    • iOS: alexa://?fragment=v2/accessory-settings/gateway?deviceid=serialnum
    • Android: https://alexa.amazon.com/?fragment=v2/accessory-settings/gateway?deviceid=serialnum

Configure the AMA Kit setup flow

The following sections describe the configuration settings used to communicate whether an accessory should begin the setup flow and the settings used to actually start the setup flow.

Configure the setting for the setup flow

To communicate to Alexa that a new or re-initialized Bluetooth accessory should begin the setup flow, use the needs_setup flag, which you should store on the accessory itself.

When the user begins the setup flow, set the value needs_setup=true on the accessory. Although the Alexa app also has a setting for starting the setup flow for a new accessory, the accessory should store the actual needs_setup=true value locally, instead of relying on the Alexa app, which might have outdated information.

On its initial connection with the Alexa app, the accessory returns needs_setup=true to the app, if the accessory has never been set up before, and on later connections returns needs_setup=false. The Alexa app determines if the accessory needs setup by checking the value of the needs_setup parameter in deviceInformation.

Start the setup flow for an accessory

To start the setup flow, Alexa app sends a message to the accessory that the app has started the setup process. Have your accessory respond with a success message. Customize these messages for your accessory and should be flexible for your implementation. The default behavior is for the app to send a start_setup message followed by a complete_setup message.

Overview of the AMA Kit setup flow.

The AMA Kit requires a third-party device to execute a setup flow when a user is setting up a new device for the first time. The setup flow includes the following high-level tasks:

  1. Download and install the Alexa app, if the user hasn't already installed it.
  2. The Alexa app discovers and pairs with the AMA Bluetooth device.
  3. Complete the Alexa setup.

Step 1: Download and install the Alexa app, if needed

The following workflow walks through a representative sample set of steps for first-time users of the Alexa app who are setting up their new AMA devices. The process starts when a user opens the accessory companion app, which prompts the user to download and install the Amazon Alexa app from a deep link.

Note that before the Alexa setup process starts, the accessory companion app should complete the following tasks:

  • Use Bluetooth to pair the accessory companion app with the AMA device.
  • Perform any firmware updates to the AMA device.

Use the following flow to have the accessory companion app prompt the user to download and install the Alexa app:

  1. On their phone, the user opens the accessory companion app.

    The accessory companion app searches for the Alexa app, which the user hasn't yet installed on their phone.

  2. The accessory companion app uses a deep link to prompt the user to install the Alexa app from the appropriate app store.

    AMA setup sequence
  3. The user installs the Alexa app. When the user opens the Alexa app for the first time, the app prompts them to sign into their Amazon account.

  4. In the accessory companion app, prompt the user to configure the Action button for the AMA-enabled device so that Alexa is set as the voice assistant for that device.

  5. After the voice assistant is set to Alexa, within the accessory companion app, provide a deep link to the Alexa app Devices screen, as described in Set up deep links within your accessory companion app

  6. Prompt the user to click the link to the Alexa Devices page to set up the device in the Alexa app.

    Alexa app Settings

Step 2: The Alexa app discovers and pairs with the AMA Bluetooth device.

With the Alexa app installed and opened to the Devices page, the user selects a device to set up, and the Alexa app "discovers" the AMA-enabled device.

The device discovery process has the following steps:

  1. The user taps the + sign in the upper-right corner to add a new device:

    Alexa app Settings

    The Alexa app displays the Add … menu:

    AMA setup sequence
  2. The user chooses Add Device.

    The Alexa app displays a list of device types:

    AMA setup sequence
  3. From the menu of available device types, the user chooses the device type, such as Headphones.

    The Alexa app displays a list detected devices:

    AMA setup sequence
  4. The user taps the device that they want to set up.

    The Alexa app prompts the user to begin setup on their device:

    AMA setup sequence
  5. If necessary, the Alexa app prompts the user to grant the app Permissions for Location and/or Microphone.

    setup permissions

Step 3: Complete Alexa setup

The following steps describe the process flow for a user who already downloaded the Alexa app and paired their AMA device with the Alexa app.

  1. If the user is new to the Alexa app, the app prompts the user for some personal information to complete the configuration.

  2. The Alexa app notifies the user that setup is complete. The user is now able to use Alexa with their AMA device.

    setup complete