Communication Related to your Skill Customers

Use the following best practice to create and maintain independent records necessary to identify your customers with the identifiers we will provide, if we send communications related to your skill customers. This best practice example is for both account-linked and non-account linked skill designs.

To get a user ID

You get a user ID by subscribing to one or more of the following events.

If your skill uses account linking – At a minimum, you should subscribe to the account linked event and skill disabled event.

If your skill doesn't use account linking – You can use the user ID provided in each request to identify the customer. The user ID for a given customer generates when the customer enables your skill in the Alexa app. Every subsequent request from that customer to your skill contains the same user ID unless the customer disables the skill.

To learn more about subscribing to skill events, follow the instructions on the Skill Events in Alexa Skills.

Skills using Account Linking

Account linked event

This event provides you with the user ID and the Access Token of the skill user in question. You can then use this data to store the user ID against your customer's account ID to retrieve the account ID on your end. You must use the Access Token and present it in the account linked event. This is because there is a new user ID generated on every skill enablement. You must maintain multiple user IDs and map each to a single account ID on your end.

Skill disabled event

This event sends when a customer disables the skill. You use this event to update the EndDatetime column of your table. If a user ID is present in the skill disabled event, use this value to determine which row to update.

Sample Skill manifest to subscribe to required events

Events section of skill manifest, for a skill looking to subscribe to events.

"events": {
    "endpoint": {
        "uri": "arn:aws:lambda:..."
    },
    "subscriptions": [
        {
            "eventName": "SKILL_DISABLED"
        },
        {
            "eventName": "SKILL_ACCOUNT_LINKED"
        }
    ],
    "regions": {
        "NA": {
            "endpoint": {
                "uri": "arn:aws:lambda:..."
            }
        }
    }
}

Datastore schema

Here is an example of a datastore schema that follows best practices.

ID AmazonUserID AccountID StartDatetime EndDatetime
a121jkawkj amzn1.ask.account.AF4RYW7RN5H hello_2167671@gmail.com 2019-09-01T00:00:00Z 2019-09-06T00:00:00Z
b211nacxm amzn1.ask.account.AHAD5TCOKQY hello_2167672@gmail.com 2019-09-15T00:00:00Z 2019-09-20T00:00:00Z

Values

  • ID: Primary key of your datastore table.
  • AmazonUserID: User ID present in the account linked and skill disablement event. Also present in each request to the skill.
  • AccountID: The ID of a customer in your internal system.
  • StartDateTime: The time when an account was linked.
  • EndDateTime: The time when a skill was disabled. This value is null if the skill disabled event hasn't been received.

Authentication of event messages

If your HIPAA-eligible skill has a custom built endpoint for the event registration endpoint, you should validate the request signature documented in the SDK guidelines. This applies for both the custom skill endpoint and the event registration. If you are using a lambda, the authorization is already set up, because you have already set the Alexa Skills Kit as a trigger.

Skills without Account Linking

If you configure a skill without account linking, you can identify a customer by listening to the skill enable event and skill disable event. This means you must build a system that uses a user ID and time-stamp to identify your customers. You also get the userID in each request. You should map the userID to their account ID, similar to the database schema described earlier.

For more details about this process, see when to use account linking.

Was this page helpful?

Last updated: Oct 13, 2023