Improve the Customer Experience for Your Custom Skills with Personalization : Alexa Blogs

Alexa Blogs

Want the latest?

Subscribe to Alexa Announcements
Subscribe via RSS

alexa topics

What You Can Personalize

There are multiple options for what you can personalize in custom skills. You can use personal information to provide a more localized experience, persistent attributes to store customer preferences between skill invocations, or account linking to provide information from a third-party service for the customer.

If your skill needs to access the customer’s name or address, there are many ways to obtain and use this information. Personal information such as name and address is best obtained using the Customer Contact, the Device Address, the Device Settings and Location Services APIs since these leverage permissions and don’t require the extra step of account linking. In use cases which aren’t serveAd by these APIs, accessing personal information stored in a third-party service or platform can be done securely by using account linking. You can also use Voice Profiles to provide a personalized experience for recognized users of your skill.

If you only need to persist customer data (inputs, preferences, or related metrics) across skill sessions which is generated within the scope of your skill, then use Persistent Attributes or your favorite database system, using the “user.userId” attribute as the primary key.

Smart home, baby activity, meeting, and video skills must use account linking to connect to the relevant cloud service provider in order to work. For example, to control a smart light bulb, the customer has to be linked to the cloud service of the smart light bulb provider so that it can be turned on or off. Other ways you can use account linking to enhance your skill include:

Linking an Alexa customer to an existing profile in your user database to provide a contextual experience within the skill.
Providing a voice alternative to operations that are already available in your mobile app or website (for example, booking a service).
Retaining user preferences and/or history across skill enablements.
Provisioning new customers through your skill when you want those customers to be able to move seamlessly between their Alexa-enabled device and your mobile application/website.
Securely verifying a Personal Identification Number (PIN) which your skill requires before an action is taken. This is common in financial services skills.

Account linking uses OAuth 2.0. (If you are unfamiliar with some of the OAuth terminology, check out OAuth Roles and The Alexa Skills Kit section of our documentation). OAuth 2.0 servers typically support two protocols for initiating a secure access token exchange: an authorization code grant and an implicit grant. Supporting the authorization code grant is required for smart home, video, and meetings skills, as well as for music skills (if the music skill uses account linking). Custom skills can use either, but code grants are recommended since the access token can automatically be renewed when it expires. Custom skills, similar to music skills, do not have to require account linking and can be enabled in an “unlinked” state. Baby activity skills require mutual authentication, which is like each side setting up a code grant—each side ends up with an access token and refresh token (which is used to get new access tokens when they expire). In the typical code grant account linking scenario (and only half of the mutual authentication scenario), ASK manages the access token for you, including refreshing the access token. Once a customer’s account has been linked, you receive an access token in the “user” block of the JSON request object.

Comparing Personalization Options

Now that we’ve covered the options that you can use to personalize your custom skills, the real question is, which one should you use? First, you should choose the method which meets your use case. Second, you should always choose the method that requires the least amount of setup for your customers. Consider this carefully when faced with more than one suitable method. Permission-based APIs require less setup for the customer, so should be the preferred option over account linking when possible. Also, when designing your skill’s experience, remember that customers may choose not to grant you permissions that you request, or may not link an account. Consider how you can still provide the best possible customer experience in these cases.

Customer Contact API and Device Address API

The Customer Contact API gives your skill access to the customer’s name, email address, and phone number. Customers must give permission to your skill before it can access the following information:

Name (full name or first name)
Email address, if the customer has provided one
Phone number, if the customer has provided one

Note: The customer details above are those provided by the customer as part of their Amazon account. Customers are required to provide either an email address or phone number, but not both.

The Device Address API gives your skill access to the customer’s full address or country/region and postal code. Like the Customer Contact API, customers must give permission to your skill before it can access that information. You can configure your skill to request either the detailed (full) address, or just the more general country/region and postal code. To help maintain customer trust, only request the level of detail that you require.

The device address details are optionally provided by the customer when they set up their Echo device in the Alexa app or website. This information is specific to the device the customer is using and may not be the same as their shipping or billing address.

The Customer Contact API and Device Address API are enabled by configuring skill Permissions in the Developer Console under the Build tab. Access to the data provided by these APIs must also be granted by the customer after enabling the skill. Any data obtained from these APIs should not be cached, and should be requested during each skill session which requires it.

Device Settings API

The Device Settings API gives your skill access to preferences set by the customer, such as time zone, distance units (such as miles or kilometers), and temperature units (such as Fahrenheit or Celsius). This API differs from Customer Contact API and Device Address API as it does not require the customer to grant permission to the skill to access this information.

Like the Device Location API, this information is specific to the device the customer is using and not tied to the customer’s account. Since it is possible for a customer to configure devices differently, access this information using this API rather than inferring it using other data.

Location Services API

With location services, your skill can ask the customer's permission to use the real-time location of their Alexa-enabled device, only at the time of their request, in order to provide more enhanced services. This API returns geo-coordinates (including latitude, longitude, and altitude) as opposed to an address. This API will only be useful in cases where the Alexa-enabled device is mobile; stationary devices are unlikely to provide geo-location capabilities. Like the Customer Contact and Device Location APIs, customers give permission before your skill gains access the location data.

Login with Amazon

Login with Amazon (LWA) provides a free, convenient, and highly available OAuth2.0 server which you, as the skill developer, can use to authenticate your customers. Since it uses their Amazon account, customers aren’t required to create a new account. Once a customer’s account is linked, your skill can obtain basic user profile information including name, email, postal code, and a user ID. This user ID is unique for that user in connection with your developer account. If the same customer links their account with another developer’s skill in the same manner, the user ID will be different. It is also different from the user ID provided in the Alexa skill request payload, even if the customer uses the same Amazon account in both places. If you use LWA, customers will need to log in to their Amazon account again and consent to share this data with your skill. Just logging into the Alexa app does not provide this consent.

Note: LWA provides basic profile information and supports both authorization code and implicit grants. If you require custom attributes or you have branded imagery and colors you want to use on the login (authentication) page, then consider using Amazon Cognito User Pools.

Amazon Cognito User Pools

Amazon Cognito User Pools provide a secure user directory that scales to hundreds of millions of users. As a fully managed service, Cognito User Pools are easy to set up without any worries about standing up server infrastructure.

Amazon Cognito User Pools can be used to:

Create and reference custom attributes
Customize the authorization web page.
Provide workflow hooks to capture events such as unlinking from the skill
Federate to third-party identity providers (social, OIDC, SAML 2.0) where customers already have accounts.

Cognito User Pools allow you to set up your own user directory and OAuth2.0 server. They support both the Authorization code grant and Implicit grant flows. Cognito User Pools also include functionality to allow users to create an account in the User Pool before linking their account. You must support account creation in the authorization flow to pass certification.

Unlike LWA, Cognito User Pools allow for customization of the authorization web frame (for example, images and CSS). In addition to responding to skill events sent by Alexa, you can also trigger additional workflows when events happen within the User Pool. For example, a trigger fires when a user completes the linking process or when a user unlinks your skill.

During the account linking process, the customer authenticates against your authorization end-point. This grants the skill access to data and operations that you deem necessary to fulfill the functionality in the skill as defined by the scope defined in the OAuth configuration. This provides a better customer experience because the customer doesn’t have to explicitly enable each individual permission.

Deciding on the Best Personalization Option

To recap, you should choose the personalization option that best fits your use case, and which results in the least amount of setup effort for customers. Permission-based APIs are recommended over account linking where possible, as they require less customer interaction to start using your skill. You should also consider the situation where a customer does not grant permissions to the skill (for the ASK APIs), or does not link their account. For example, if your skill uses zip code (post code) for a localized experience, but permission was not granted to your skill for the Device Address API, you could include functionality in your skill to request the zip code through voice and then store it in Persisted Attributes for subsequent skill invocations.

If you’re still not sure which one to use—or if you know which option you want to use but want to learn more—then you can use our samples to dive deeper.

Check out the Customer Contact Demo, the Device Location Demo, the Device Settings Demo, the Locations Services Demo and the Voice Profile Demo—all of which can be found in the Alexa Cookbook. If you want to try out using account linking with LWA, follow the steps in this blog post. And stay tuned for part two of this blog series, which will walk you through using Amazon Cognito User Pools for account linking.

Regardless of what you do next, we’d love to hear about what you’re building. Tweet us @AlexaDevs and we be happy to check it out!