App-to-App Account Linking (Starting From Your App) is a specific account linking flow that enables customers to link their identity between Alexa and your service, starting from your app. It minimizes the need to enter account credentials, and thereby simplifies account linking for your customers. The end result is simple - more linked customers means more engagement with your skill.
We analyzed the customer experience of a few successful implementations and are excited to share our top 6 recommendations that can help you with your App-to-App implementation.
Note: If you build a Smart Home skill, App-to-App Account Linking (Starting From Your App) is a mandatory requirement for all Works With Alexa (WWA) product certifications since November 12, 2021.
This post assumes you are familiar with the basics of App-to-App Account Linking. In case you are not, below is a brief explanation (click on the "+").
Account linking enables your skill to connect a skill user's Amazon identity with their identity from your OAuth provider. With App-to-App Account Linking, you can allow your customers to start the account linking flow either from your app or from the Alexa app. The customer can complete it with a few touches, thereby minimizing the need to enter account credentials and providing a natural interface between your app and the Alexa app. When you start the account linking flow from your app, your customers can:
Our recommendations are based on the assumption that your customers have the Alexa app and your app already installed on their smartphone, and they initiate the account linking flow from your app. We are not touching specific recommendations on the fallback mechanism with Login with Amazon in case the Alexa app is not installed, but make sure to address it in your implementation.
Summary: Overall App-to-App Account Linking User Flow
Before we get into recommendations, we want you to understand the end-to-end user flow so that you are clear on the big picture, and where each of our recommendations fit. We will get into more details on parts of it further down in this blog post.
Please take a moment to be aware of these common pitfalls. We received feedback from developers that they struggle to understand a) what the “user's authorization code” is, and where it comes from, and b) figure out how it works in OAuth flows.
As a result, we updated our sequence diagram in the documentation.
We are referring to the sequence diagram that can be found in the how-it-works on the developer documentation for App-to-App account linking starting from your app.
In the traditional account linking flow using the authorization code grant, authorization codes are generated in the step in which users login to their account on your identity provider (IDP), and are asked to provide their consent to link with Alexa.
In App-to-App account linking however, users are already logged into your app and initiated the account linking flow from your app. Remember that App-to-App account linking is all about enabling your Alexa skill without having the customer entering their credentials. This implies two requirements for your identity provider:
A complete App-to-App Account Linking flow does not only include the linking, but also the unlinking part. In order to successfully implement unlinking, you need to persist the token pair received during the "App-to-App" flow for future unlinking requests via your app.
It is important to understand that the App-to-App Account Linking token used for skill linking (scope=alexa::skills:account_linking) cannot be used for other skills operations such as sending events to the Alexa Gateway or calling Alexa APIs within an in-skill session. Typically, for Smart Home Skills developers to send events to the Alexa Gateway, this requires the developer to maintain a second Alexa token pair which shall be obtained from the Alexa.Authorization.AcceptGrant directive.
How many clicks are required to initiate the account linking flow from your app's home screen? Make sure to review the visibility and accessibility of the account linking flow initiation for voice assistants in your app. Depending on your app’s overall design guideline and interaction concept, the lowest number of clicks from your app’s home screen to initiate the account linking flow can be three. However, more common flows look like this: The user touches the (1) Burger menu, (2) then "Voice Assistant & Apps" (or similar wording), then selects (3) "Amazon Alexa", (4) clicks on "Allow" to initiate the App-to-App Account Linking Flow.
Dos: Always try to keep the number of clicks required to initiate the linking flow as low as possible.
Don’ts: Don't hide the Alexa "App-to-App linking" button too deep inside the navigation structure of your app. Doing so will reduce the number of account linking flows that are initiated from your app.
What happens if users cancel the account linking flow at some point? What is the next screen, users will see? Users do not expect to see any "Oops, something went wrong" message, since it was their decision to cancel the account linking flow. Do you gracefully handle errors and timeouts? Do you provide clear enough information about what went wrong?
Dos: Make sure that the screens in your app are providing context specific texts and visuals.
Don’ts: Do not show generic screens to your users that don’t provide clear information about what just happened.
What: Make sure to check for the skill enablement status for a given user, in order to display the right option for linking or unlinking.
Why: This is an important aspect of the user experience. Users who have linked their account expect to see that state represented when coming back to the linking screen within your app. They will be confused if you give them the possibility to link their account once again. The other way around, users who disabled your skill via any other interaction do not want to see the account linking status as "Linked with Alexa" within your app.
How: You should internally store the information that users have linked their account with Alexa using the App-to-App linking flow. As explained in the "Before you start" section, you can identify those based on a second token pair (with scope=alexa::skills:account_linking). However, just checking for the presence of the token pair is not sufficient as the user can disable a skill via the Alexa app or the Amazon retail website. To overcome that issue, you have two options:
3 Things to Remember:
What: What are the things users have to do after they installed your app and logged in for the first time? It is a common practice to have some onboarding steps to complete the account setup in your app. At the end of the account/app setup, we suggest to implement an additional screen that directs users towards your App-to-App account linking flow.
Why: This will reduce the number of clicks for users to successfully link their accounts with Alexa to a minimum of two clicks", thereby improving awareness and driving adoption for your skill.
How: It is common that a user is guided through a series of splash screens that help to complete the basic setup. We noticed a recurring pattern in which the user is suggested to complete third party integrations at the end of the app or device setup flow. The user can decide to click on the Alexa logo and gets redirected into the App-to-App account linking flow. If a user instead decides to skip the linking process, it is a good practice to show a second splash screen on where in the menu structure of your app can they find the linking flow later.
What: Drive targeted communications, or call to actions to users that have not succesfully linked their Alexa account by informing them about your new feature "App-to-App Account Linking".
Why: You might still have a percentage of your customers that potentially don't know about the capability to voice control your devices or services by linking with Alexa. This will be most helpful for customers who tried to link in the past, but did not manage to complete the account linking flow. Your messaging will have a high chance to convert into actions for that particular customer group.
How: What communication channels do you use to provide updates about new functionalities to your customer base? There are a number of options including push notifications, "what's new pop-up screens" after updating the app to a new version, release notes in app stores, blog posts or mass mailings.
Dos: Launch targeted splash screens in your app to inform customers that are not yet linked.
Don'ts: Do not target 100% of your customers with a splash screen.
What: While we hope your customers will love the experience that voice forward control adds to their daily life, some customers might not want to keep using Alexa. Give them an option to unlink the Alexa skill from within your app.
Why: If you do not allow users to unlink their accounts from the same place you asked them to perform the linking, you will increase the risk of having confused or frustrated users.
How: The easiest option for a user is to have the unlink functionality on the same screen as the one on which they initiated the account linking flow. While unlinking is a simple "DELETE" API call for users who linked their accounts with the App-to-App flow, there are few things to consider for this implementation.