Best Practices to Successfully Implement App-to-App Account Linking (Starting From Your App) in Your Skill
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.
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:
- Discover your Alexa skill through your app
- Initiate skill enablement and account linking from within your app
- Link their account without entering their account credentials in either your app or the Alexa app, as long as they are logged in to both the apps on their mobile device
- Link their account from your app using Login with Amazon (LWA), when the Alexa app isn't installed on their mobile device
- Unlink their skill account from your app
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:
- Your IDP shall be compatible with OAuth authorization code grant type.
- Your IDP shall have the ability to programmatically generate the "user's authorization code"! Without that capability, the entire App-to-App account linking experience won't work.
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.
Example: Common User Flow to Initiate App-to-App Account Linking
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.
- Good Example: Success message at the end of the App-to-App account linking flow should show “Congratulations. Your account is linked with Alexa. You can now request rides by voice. Start saying: "Alexa, ask Ride Hailer to order a taxi."
- Good Example: If something takes longer than expected, provide a progress indicator to your users and let them know what's happening. Avoid blank screens at all times, and consider implementing an automated retry pattern for timeouts.
Don’ts: Do not show generic screens to your users that don’t provide clear information about what just happened.
- Bad Example: At the end of the account linking flow, do not show a “You’re already linked with Alexa” message. Make sure to show the right text at the right time.
- Bad Example: Do not show error messages for user cancelled account linking flows. Most users expect to be redirected to the last screen from before the account linking.
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:
- Asynchronous: The best solution is to handle skill disablement by subscribing to Skill Events.
- Synchronous: If you don't have a way to handle the event subscription, you can also send GET requests to check the status via the Alexa Skill Activation API. However, this gives you a successful response only for users who linked their account using App-to-App Account Linking. For other users, you will receive a 403 Forbidden error stating: "The Amazon access token is invalid or doesn't have access to make this request."
3 Things to Remember:
- You can't rely on the Alexa token pair being present in your backend to decide if a user has linked his account or not.
- Do subscribe to Skill Events to handle skill enablements and disablements from outside your app.
- You can only interact with the Skill Activation API for users who linked their account via App-to-App account linking.
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.
Example: Out-of-box experience including App-to-App Account Linking & Information on link 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.
- The most effective option will be to launch a splash screen (similar to what we touched in #4) for those users who are not yet linked with Alexa to guide them towards the App-to-App Account Linking flow.
Don'ts: Do not target 100% of your customers with a splash screen.
- Be careful not to target 100% of your customers with the splash screen about App-to-App Account Linking.
- Do not confuse your existing customers who have already linked their account with Alexa
- Users who have already seen a splash screen should not see it a second time.
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.
Example: Unlinking flow only for users who previously linked their account with the App-to-App flow
Technical Implementation
- For users who linked their accounts following the App-to-App account linking flow, send a DELETE request for your skill with a valid token that contains the alexa::skills:account_linking scope to the Alexa Skill Activation API.
- Note: This will not work for users who linked their accounts via the traditional account linking flow as you will not have a token with that particular scope. Allowing those users to unlink directly from your app will lead to HTTP 403 errors.
- Here is what you can do: Identify users who did not follow the App-to-App account linking flow and put a deep link behind the "unlink" button to redirect them to your skill detail page in the Alexa app. If the Alexa app is not installed, users will be redirected to your skill details page on the Alexa website. This is where the user can finalize the unlinking. The URL is https://alexa.amazon.com/spa/index.html#skills/dp/{skillAsin} for both Android and iOS. As fallback, if the Alexa app is not installed, redirect your users to https://www.amazon.{domain suffix}/dp/{skillAsin}.
Use App-to-App Account Linking and New Skill Activation API to Simplify Skill Setup
Introducing New Works with Alexa (WWA) Badge and Requirements
