Wi-Fi Provisionee App and Backend Integration Guide

Prerequisites
Integration Components
- Front-End Integration Components
  - App-to-App Account Linking
  - Login with Amazon Integration
- Backend Integration Components
  - Post-Wi-Fi Attach Flow
Integration Scenarios
Testing End-to-End Customer Experience
Certification
Skill-Device Association Event (SDAE) API
- Customer-Device Association Directive (CDAD) API
Branding and Customer Experience Recommendations

This guide provides the Wi-Fi Simple Setup (WSS) integration steps from the perspective of an end-to-end customer. The guide covers modifications to your mobile applicaiton and cloud backend to enable the Frustration-Free Setup experience for your customers.

Prerequisites

You need to meet the following software criteria:

Provide ether an iOS app, Android app, or both.
Implement App-to-App Account Linking and Login with Amazon (LWA) flow and integrate with the Alexa Skill Activation APIs.
Integrate with two new Smart Home Skill APIs (SDAE, CDAD).
Integrate Proactive Discovery in your Smart Home skill.

Integration Components

This document provides integration guidance for you to integrate the WSS customer experience directly into your mobile app and backend. It supports the following scenarios:

'First Device Setup': Existing Amazon customer buys the device from Amazon but has not performed Smart Home skill linking before power-on.
'2-to-N Device Setup': Existing Amazon customer buys the device from amazon and completes Smart Home skill linking before power-on.

The following section provides the building blocks of integration supporting all of the listed scenarios.

Front-End Integration Components

The Front-End Integration incorporates App-to-App Account Linking / Login with Amazon (LWA), and Alexa Skill Activation API.

App-to-App Account Linking

App-to-App Account Linking allows you to connect the identity of an Alexa service customer with a customer account in their account pool, and thereby personalize their Alexa service experience.

With App-to-App Account Linking, a customer can enable a skill and link to their Amazon account by acknowledging a linking request. The customer can do this when they have both the Alexa app and your app installed on their mobile device. The customer starts from your app, which redirects the customer to the Alexa app to obtain consent for account linking. After the customer gives consent in the Alexa app, the Alexa app redirects the customer back to your app. This flow eliminates the need for a customer to enter account credentials in either of the apps. Amazon uses Reciprocal OAuth, which builds on top of OAuth 2.0 and allows OAuth token exchange in both directions.

To get started:

Obtain Amazon Client ID: If you have an Alexa Smart Home skill for your device and send asynchronous events to the Alexa service, then you should already have an Amazon (Alexa service) ClientID. If you don't have an Amazon Client ID for your skill, please follow these steps:

a. Log into your ASK Developer Console.

b. Navigate to the 'Account Linking' section under the 'Build' tab.

c. Enable 'Allow users to link their account to your skill from within your application or website'.

Once you click on 'Save', the page shows you your Amazon (Alexa service) Client ID and Client credentials.

Add redirect URLs to “Your redirect URL's” field.
Implement Universal Linking (iOS): When the customer clicks on 'Simple Setup by Amazon' or 'Sign in', use Universal Linking to launch the Alexa URL (provided separately) with the Authorization Request parameters (Amazon Client Id, state, scopes, response_type, redirect_uri and stage). Use the following access scopes: (i) "alexa::skills:account_linking", and (ii) "frustration_free_setup::device:setup". Call open(_:options:completionHandler:) method in iOS to launch Alexa app. It launches the Alexa app, if installed on the customer's mobile device, and takes the customer to the consent screen where they give consent for device set up and skill account linking. Once the customer gives consent, the Alexa app redirects the customer back your app with Universal Linking. The redirect process passes the Customer's Amazon Authorization Code between app. When trying to open the Alexa URL, the app MUST use the "UniversalLinksOnly : true" option. Your app should not use this option when trying to open the LwA URL, and the customer does not have the Alexa app installed on their mobile device.
Exchange the Authorization Code for the Amazon Access Token from LWA.
Obtain your app's Authorization Code for the customer (from your skill authorization server).
Call Alexa Skill Activation API with the Amazon Access Token and your app's Authorization Code. Finally, the Alexa service calls your authorization server to exchange your app's Authorization Code for an Access Token, and stores it in the Alexa service, thereby completing skill enablement and account linking.

Before or after the LwA flow, you should check if the customer has enabled your Alexa Smart Home skill. If they haven't, present them with the App-to-App Account Linking flow for skill enablement in your app. Please use Login With Amazon integration when the customer does not have the Alexa app installed on their mobile device. Login with Amazon allows you to leverage the Amazon.com user authentication system to connect with their users.

To get started:

Complete Steps 1-2 in App-to-App Account Linking section.
In Step 3, your iOS app calls open(:options:completionHandler:) to launch the Alexa app. If this method returns success=false, your app should launch the LWA login screen using the LWA SDK. In this flow, the customer enters their Amazon credentials, authenticates themselves with Amazon, and gives consent for device set up and skill account linking. Use the same access scopes as in App-to-App Account Linking.
Complete Steps 4-6 in App-to-App Account Linking section.

Refer to the LwA Documentation for more details:

Backend Integration Components

The Backend integration is the process of integration the provisionee device with the device manufacturer's cloud, and then from the device manufacturer's cloud to the FFS and Amazon Smart Home services cloud. Your application must trigger these flows when the provisionee device connects to the customer's home Wi-Fi network.

Post-Wi-Fi Attach Flow

Post-Wi-Fi Attach Flow is a sequence of API calls made between the Provisionee device, your cloud, and the Amazon Smart Home Service. After the device has successfully connected to the customer's home Wi-Fi network, the device may proceed with establishing connections to the device manufacturer's cloud. At this stage, the manufacturer's cloud does not have enough information to associate the device with a customer's account reliably. To obtain the information about the Amazon customer associated with the device, you should use your Smart Home skill to provide the connecting link between the customer's Provisionee device, the device manufacturer's cloud account, and the Amazon account.

There are two Smart Home APIs which are used to establish this connection:

Skill Device Association Event (SDAE)
Customer Device Association Directive (CDAD)

The following sequence diagrams depict the use of these API calls. Appendix A of this document provides the detailed specifications of these APIs.

Integration Scenarios

This section describes each of the integration scenarios in detail with sequence diagrams.

Zero Touch Setup (ZTS) Customer Experience:

It is essential to understand the Zero Touch Setup customer experience. The following is the criteria for a customer's newly bought Provisionee device to be eligible for a Zero Touch Setup during Simple Setup.

The customer bought their device through WSS participating retailer such as Amazon.com.
The customer has a provisioner (EFD, Fire TV, 3rd party router) in the vicinity, hosting a hidden WSS compliant SSID.
The customer has at least one Wi-Fi password saved in the Amazon Wi-Fi locker.
The customer links their Alexa Smart Home skill

Environments meeting these criteria enable automatic setup and connection to the customer's Wi-Fi network. The WSS architecture terms this experience Zero Touch Setup (ZTS).

Enabling ZTS on your provisionee device requires integration with the following three scenarios:

'First Device Setup'
'2-to-N Device Setup'

First Device Setup

This integration scenario addresses the use case of an existing Amazon customer, who hasn't done Smart Home skill linking, turning on a device purchased via Amazon.com. As the customer has not yet completed skill linking, they must go through the Login with Amazon (LWA) / App to App Account Linking flow to initiate skill linking and accomplish ZTS for their provisionee device.

LWA and App-to-App Account Linking assist with authentication and authorization. Once the user selects the simple setup option and local discovery discovers the customer's new device, your application calls the LWA library to authenticate the customer into their Amazon account.

If the customer has another Amazon application installed, like the Amazon Shopping app, the LWA SDK authenticates the customer through the installed application and returns an auth token. Make sure to use the appropriate scopes in your request (see in the sequence diagram). This process links the customer's account on your cloud, and with the customer's Amazon account.

This diagram shows the LwA and App-to-App Account Linking flow CX corresponding to the following sequence diagram:

2-to-N Device Setup

This integration scenario addresses the use case of an Amazon customer purchasing multiple devices from the same manufacturer. This scenario assumes that the customer already has a linked Alexa Smart Home skill before powering on the Provisionee device. With these criteria met, the Provisionee device should complete ZTS without customer intervention. When ZTS for a provisionee is complete, the Amazon cloud sends a Customer Device Association Directive (CDAD) directive to your Smart Home skill.

You should implement the Proactive Discovery API to complete the Discovery of the device in the customer's Alexa service account. This event notification enables you to send push notifications to customers.

Race Condition Possibility: There may be a race condition where ZTS starts (usually takes between 30-60 seconds) and the customer opens up your application to kickoff setup. We are working on a new API to assist with this case. Please review with your Solutions Architect for more information.

Testing End-to-End Customer Experience

To test the end to end flow, Amazon provides test credentials. Please visit the Frustration-Free developer portal at developer.amazon.com/frustration-free-setup

Certification

Ensuring compliance with the WSS specification and implementation ensures a consistent and secure experience for our customers. Amazon requires that Wi-Fi Simple Setup-compatible devices are validated and certified. Please review the Provisionee certification plan for more details.

Skill-Device Association Event (SDAE) API

Your application should send the AddOrUpdateDeviceAssociationReport message that contains information about the WSS provisioning session and the device. This event notifies the Amazon WSS service that device provisioning is completed and allows the Alexa service to identify the associated skill for the device. The event contains the following fields:

Scope Object:

Field Name	Description	Field Type	Required
Scope.type	Acceptable value is “BearerToken”	String	Yes
Scope.token	The access token with “alexa::device_association_report:write” permission.	String	Yes

Device Object:

Field Name	Description	Field Type	Required
Device.sessionToken	The WSS session token obtained during device credentials provisioning. 'sessionToken' is a value read from the "ComputeConfigurationData" API response during setup with key "FFS.SessionToken".	String	Yes
Device.signature	The signature generated by signing the sessionToken using the private key of the device with the SHA256withECDSA algorithm.	Base 64 encoded String.	Yes
Device.id	The unique identifier of the device used by your application to identify the device. This identifier must be unique per provisioning session. It is recommended to be a global device identifier concatenated with the WSS SessionToken.	String that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ &	Yes
Device.namingCategories	Indicates how the device should display in the Alexa app. See Display categories for supported values.	String array	Yes

Sample AddOrUpdateDeviceAssociationReport

POST /v3/events HTTP/1.1
Host: api.amazonalexa.com
Authorization: Bearer access-token-from-Amazon
{
  "event": {
    "header": {
      "namespace": "Alexa.SimpleSetup",
      "name": "AddOrUpdateDeviceAssociationReport",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "device": {
        "sessionToken": "WSS-session-token-obtained-during-provisioning",
        "signature": "sessionToken-signature",
        "id": "device-identifier",
        "namingCategories": ["SWITCH"]
      }
    }
}

Bearer Access Token for Skill-Device Association All AddOrUpdateDeviceAssociationReport requests need to be authenticated. Your application needs to send an access token for request validation. You can obtain an access token using the “client_credentials” grant type, using their LwA Client credentials associated with the skill. The developer portal generates the LwA ClientID at the Smart Home skill level when you enable permission for sending Alexa services asynchronous events.

Sample request:

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/json
{
      "grant_type": "client_credentials",
      "client_id": "<lwa-client-id>",
      "client_secret": "<lwa-client-secret>",
      "scope": "alexa::device_association_report:write"
}

Here's a Sample Response from Login with Amazon:

{
    "access_token": "<access-token>",
    "scope": "alexa::device_association_report:write",
    "token_type": "bearer",
    "expires_in": 3600
}

NOTE: The Access Token is different than the one obtained during skill linking via “AcceptGrant” directive. You should not use the token retrieved from the AcceptGrant directives and should request tokens using for WSS purposes.

The Access Token obtained should be populated both in the HTTP Header “Authorization” and also in the payload section:

POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
*Authorization: Bearer <access-token>*
Content-Type: application/json
{
...
        "scope":{
            "type":"BearerToken",
     *       **"token":"<access-token>"*
         }
...
}

Setting the Host Attribute Your application needs to set the value of the Host attribute at run-time. The “ffsGetConfigurationValue” function of the WSSoWiFi SDK returns the API gateway endpoint value you should use for the Host attribute. Use the “FFS_CONFIGURATION_ENTRY_KEY_ALEXA_EVENT_GATEWAY_ENDPOINT” configuration key defined in our SDK with the “ffsGetConfigurationValue” function.

Responses

Successful Response: On success, the Alexa service returns 202 to the client.

Error Responses: Error responses have the following format:

{
    "header": {
        "namespace": "System",
        "name": "Exception",
        "messageId": ""
    },

    "payload": {
        "code": "",
        "description": ""
    }
}

Payload Fields:

Field	Description
code	An exception code returned on error.
description	Additional details for logging and troubleshooting (Should not be surfaced to customers).

Response Codes and Retry suggestion

Error codes are either Client Based (4xx) or Server Based (5xx)

HTTP Status Code	Error Message	Cause	Solution
400	Invalid/Bad request	The content type for the request was not valid.	Verify the JSON request matches the format in the Smart Home skill API Message Reference. Retry the request after fixing the JSON.
401	The access token is invalid or not present	The Bearer token provided was invalid	Check bearer token and make sure the token is valid and is not expired. Retry the request after fixing the bearer token.
403	Access token does not have sufficient permission(s) to authorize the request	Bearer token provided doesn't have sufficient permissions.	Check the bearer token has sufficient permission for posting the event. "alexa::device_association_report:write", Retry the request after fixing the bearer token
404	The skill does not exist in the live stage	skill is disabled, or it is not set up for live stage	Ensure the skill is enabled, and it is setup for live stage.
413	Request size is too large	Request size is too large. Returned when Event exceeds the permitted size limit.	Fix the event size and then retry the request.
429	Your request is throttled.	The number of requests was too high.	Verify the number of requests made per minute. It might be too high.
500	Internal Server Exception	Internal Service Exception.	Retry 3 times with roughly a second between each try.
503	Service Unavailable	The service is currently unavailable or busy	Retry 3 times with roughly a second between each try.

Customer-Device Association Directive (CDAD) API

Once the Alexa service receives a valid AddOrUpdateDeviceAssociationReport from you, and the Amazon customer who owns the device has enabled the skill, the Alexa service sends the your skill a directive to associate the Amazon customer with the provisionee device. The AssociateCustomerDevice directive allows you to associate devices with customers.

For you to correlate this request back to the provisionee device - the AssociateCustomerDevice directive contains -

A Scope object that contains an access token obtained from your skill during account linking.
The device identifier obtained from you during skill-device association along with a list of preferred friendly names.

You are expected to send back the standard Alexa service sync response as documented in Send Events to the Event Gateway.

Sample AssociateCustomerDevice:

{
  "directive": {
    "header": {
      "namespace": "Alexa.SimpleSetup",
      "name": "AssociateCustomerDevice",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "correlation-token"
    },
    "payload": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "device": {
        "id": "device-identifier",
        "preferredFriendlyNames": [
          {
            "@type": "text",
            "value": {
              "text": "First Switch",
              "locale": "en-US"
            }
          }
        ]
      }
    }
  }
}

Device object fields:

Field Name	Description	Field Type
Device.id	The unique identifier of the device sent during device-Skill association.	String that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ &
Device.preferredFriendlyNames	A list of friendly names generated by the Alexa service for you to use during the proactive discovery of the device.	Label array

Branding and Customer Experience Recommendations

This section covers the Amazon recommended customer experience on your mobile application.

Primer screen

Before your application presents the Login with Amazon or App-to-App Linking screens to the customers, your application should present a primer to inform the customer about Frustration-Free Setup. The action button should take the customer to the LwA screen. A cancel button should send the customer to the fallback setup experience.

Suggested heading: Amazon Wi-Fi simple setup
Suggested text body: Amazon Wi-Fi simple setup helps you connect supported devices to your Wi-Fi network and the Alexa service in fewer steps. Get started by linking your {manuf} and Amazon accounts.
Suggested action button text: Link Now
Suggested cancel text: I’ll do it later

Action button style guidelines

Background color: #FF9900 (255, 153, 0)

Font family: Sans-Serif

Font color: #FFFFFF

Padding: 10px

Frequently Asked Questions (FAQ)

What happens when an application receives an AddOrUpdateDeviceAssociationReport before the customer has enabled the skill?

The Alexa service sends the AssociateCustomerDevice directives after the customer has enabled the skill. The service does this because account-linking is required before skills can receive directives.
Can an AddOrUpdateDeviceAssociationReport contain multiple devices?

No, one AddOrUpdateDeviceAssociationReport should contain only a single device. The Alexa service does not support batching at this time.
How long will the Alexa service keep information about a device association?

The Alexa service keeps device association events for 30 days. If the customer does not enable the skill within this time or loses ownership of the device, the Alexa service invalidates the device association. Is this situation, the customer would fallback to default setup flow of the device.
Is an application required to use the preferredFriendlyNames during discovery?

Using the preferredFriendlyNames is not mandatory but is strongly recommended. The Alexa service has more context about what devices already exist in a customer's home (including devices from other developers). Using the preferredFriendlyNames removes the need for customer interaction. You can later prompt the customer to rename the device.

Version	Date	Author	Description
1.0	Sept 25, 2019.	Amazon.	General Availability
1.1	Mar 22, 2029.	Amazon.	Remove out-of-date information
1.2	Jun 12, 2020.	Amazon.	Remove out-of-date information

Last updated: Nov 04, 2020