At Amazon, we obsess over a few things including customer satisfaction and data. We've spent a lot of time analyzing all of the customer reviews left on Alexa skills, and we have identified a few trends. One of the top drivers of negative feedback on skills is account linking. This is not surprising since it is one of the more complex features to implement.

We have attempted to distill the feedback into a set of best practices. The account linking documentation is a good starting point, but adhering as closely as possible to the below best practices will help you avoid some of the pitfalls that other developers have run into, and ensure a high-quality account linking experience for your customers.

1. Provide Test Accounts and Testing Instructions

When you submit your skill for certification, you have the option to provide testing instructions for our certification team. This is an ideal place to provide a set of test credentials to help our certification team exercise the functionality of your skill. But it's typically impossible to thoroughly evaluate a skill with only one user account. For example, if your skill reorders the most recently placed order, you'll need a test account with recent order history. But you'll also need a test account with no order history since the user experience is likely very different.

It's also important to understand all of the various states that accounts in your system could be in. Can accounts in your system be suspended or blocked? Do new accounts need to be validated before they can be used? Do you have legacy accounts that behave differently than most of your other accounts? Do you have different account types that support different features or services (e.g. free vs. paid, etc.)?

It's important to understand all of these account states and types and to have test accounts available to exercise each of those states. Include all test accounts and instructions when you submit your skill for certification.

2. Avoid Branding Confusion on Your Login Page

When customers enable skills that require account linking, they are immediately redirected to your login page to complete the linking process. Many customers can become confused by what to do on this page. When customers see username and password fields, some assume that they are being asked to re-enter their Amazon credentials.

Your login page should have clear branding and messaging to direct users to log in to your service, so there is no confusion over which set of credentials they should use. This is especially true if your login pages were built by or hosted by a third-party (like a vendor or an agency).

If your company has acquired another company, make sure to consider the account-linking experience for both your existing and new customers who may now use the same login page, which may or may not correspond to the service they signed up for initially.

3. Provide Parity between Sign-In/Sign-Up Experiences

If your website and/or mobile apps support a sign-in mechanism like login with Facebook, Amazon, Google, Twitter, etc., make sure that your account linking login page also supports all of these same mechanisms. Otherwise, some users of your service may be unable to account link your Alexa skill. Or worse, they may end up creating a new account that they only use on Alexa, leading to confusion and a fragmented user experience.

If your website and/or mobile apps allow customers to create new accounts, you should probably support and test this flow through the account linking experience as well. Consider the scenario in which customers first encounters your service via Alexa. They should be able to seamlessly create and link a new account. If new accounts require any sort of validation, test that process in the account-linking flow to make sure that it can be accomplished seamlessly, with no delay, especially on mobile devices.

If your customers can enable multi-factor authentication on their accounts, make sure that the account linking flow still works with these secondary factors.

Lastly, ensure that it's possible for users to change credentials if necessary. After disabling the Alexa skill and re-enabling, the customer should be required to sign in again, with an option to choose a different account than the one they previously linked.

4. Support Account Recovery

With the rise of password management apps and form-filling browsers, it's not uncommon for customers to forget what their username or password is, even if they use your service every day. Be sure to support and test account recovery options as part of the account linking experience for users who have forgotten their password and/or username.

When testing, simulate failed login attempts. If multiple failed attempts trigger a CAPTCHA flow, or other abuse-prevention mechanism, make sure that these work as part of the account linking flow, especially on mobile devices.

As previously discussed, be aware of any account states that might interfere with the login process. Examples may include unverified (new) accounts, subscriptions that may have lapsed, accounts that have been suspended or blocked due to suspicious activity, etc.

When the customer fails to login, all error messaging should clearly and concisely communicate what the problem is and how they go about correcting it.

5. Include Form-Field Validation

Login screens often include form-field validation to verify that the information is well-formed before attempting to authenticate. This avoids false-negative messages to the user that their credentials are incorrect, when really the problem is something else (or an easily caught typo/copy-paste error).

Here are some common validation issues to watch for:

• Leading/trailing spaces: Rather than submit the unintended spaces as part of the username/password, strip them out or warn the user
• Unintentional capitalization: On mobile devices with soft keyboards, be careful not to bias input toward capital letters on case-sensitive fields where the user might not be expecting it
• Region-specific validation: If you are validating postal codes, addresses, phone numbers, etc., make sure that the logic you are using is correct for every region your skill is accessible in

As always, clearly communicate validation errors to the customer.

6. Test Everything Everywhere

Most account linking happens on mobile devices, but that still encompasses a dizzying array of operating systems, versions, and screen sizes. Test your login experience on popular desktop operating systems like the most recent few versions of Windows and Mac. Test the most popular browsers, like Firefox, Chrome, Internet Explorer, and Safari. Test against the most recent few versions of iOS and Android. Test on different form factors like phones and tablets. Test different screen sizes and orientations.

A common source of problems that you may encounter when testing cross-platform is when you fail to whitelist all domains that you're making external calls to. We’ve got lots of great troubleshooting tips here.

7. Test Navigation

If there are links on your login pages, check to see that they all work (the certification team will verify this as well). Verify that forward/back navigation in the browser works as well, and that you are still able to successfully complete the account linking process after navigating around. Only surface links on these pages that are pertinent to the account linking process to avoid issues. This is not the place for customers to browse your home page.

8. Help Your Customers Help Them

Your login pages should have clear guidance on how to contact your customer support. Too often, when customers run in to problems logging in, they don't know how to get in touch to resolve their problem. Often these are easy problems to solve, like forgotten user names or passwords, accounts that are locked out, etc.

9. Use the Right Tool for the Right Job

If your skill simply needs to persist data between sessions, account linking is not strictly required. The userID attribute that is provided with the request will identify the same user across sessions unless they disable and re-enable your skill. Account linking is intended to be used as an authentication mechanism for when you need to associate the identity of the Alexa user with a user in your system. Since it allows the developer to present a web page to the customer for information collection, skill developers have been expanding the scope of their account linking flows for a variety of purposes.

Account linking adds friction to the process of enabling a skill, and prevents the process from being completed seamlessly via voice. As such, it should ideally only be used when necessary. However, it may be convenient to use this mechanism to collect information that is very difficult to accurately recognize via voice, like email addresses (which often contain homophones like one and 1). Some information, like physical address, is now available via the permissions framework. As the permissions framework grows, account-linking flows should be able to be limited to authentication scenarios only and not personalization.

10. Watch Your Response Header Size

While there is no documented limit to your HTTP header sizes, we have found that it's best to stay under 2,000 characters to avoid page-loading issues. Doing so may require eliminating extraneous cookie values unrelated to OAuth account linking.

Bonus: Redirect the User

Here's a bonus tip: Don't forget to redirect the user back to Amazon when your login process has been completed. Some developers prefer to create their own branded success/failure pages without performing this final redirect. Assuming success and failing to re-direct (especially on success) could mask underlying errors that you may not have visibility in to. Learn more information here.

Build Rock-Solid Skills with Account Linking

That's a lot of stuff to test, which is a further indicator of the complexity of this mechanism. With a little diligence by your testing team, you can build rock-solid skills that rely on account linking. Following these best practices should help lay a solid foundation.

---

Build a Skill, Earn Perks

Publish your skill in the Alexa Skills Store, and earn perks like an Amazon Echo Dot or an Alexa dev shirt. Check back every month for new promotions in the UK, Germany, and the US.