@alexa-skill-components/account-linking NPM

NOTE: Alexa skill components are offered as a pre-production alpha release in developer preview. Support at this stage is limited. Our goal is to elicit feedback on our approach and design as we build toward general availability. Although we make every effort to maximize backward compatibility of this release, we can't promise it, nor can we guarantee a rapid turnaround on bug fixes. Amazon is actively updating the skill components, however, and we look forward to your feedback. Check back often to get the latest version of the components. Sign up to join us in our effort to help you build more engaging Alexa skills faster!

Pre-made Alexa skill components help you develop high-quality Alexa skills quickly. You can use the account linking reusable skill component to enhance any skill that requires a linked account. The reusable dialog validates whether a user's account is already linked in an existing ACDL skill. It checks for an access token from a linked account, automatically prompting the user to set up an account link if necessary.

Getting started

The account linking skill component works with Alexa Conversations skills created on the command line with the Alexa Conversations Description Language (ACDL) (beta). When you create your skill, you write sample conversations, or dialogs, and use the Alexa Skills Kit Command Line Interface (ASK CLI) to build and deploy your skill.

These sample dialogs represent the various conversational experiences your skill supports. Alexa Conversations uses a dialog simulator to expand your annotated dialogs into variants that train the dialog management model. The Alexa Conversations runtime hosts the trained model to process incoming events and predict actions.

NOTE: Alexa Conversations Description Language (ACDL) is offered as a beta and may change as we receive feedback and iterate on the feature.

Features

The account linking skill component simplifies the account linking development process in several ways.

Checks the user's access token and automatically prompts the user to link their account if necessary
Generates speech that briefly explains the benefits of account linking
On multimodal devices, displays a default Alexa presentation language (APL) screen
Sends a "Link account" card to the Alexa companion app on the user's mobile device

Prerequisites

Before you start, you need an Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new account. The account is free.

The ASK CLI is installed. If not, run the following command to install it.

$ npm install -g ask-cli

The ASK CLI is configured.
You have an Alexa skill that uses ACDL. To create a new ACDL skill, see Tutorial: Create an Alexa Conversations Skill with the ACDL.
Account linking is enabled for your skill. You can configure your options in the developer console.
The ASK SDK v2.11.0 or higher is installed. If not, to install it, run the following command.

$ npm install --save ask-sdk

The npm cache is empty. To clear the cache, run the following command.

$ npm install -g n

The latest version of Node.js is installed. To update Node.js, run the following command.

$ n latest

You have the latest version of npm. To update npm, run the following command.

$ npm install -g npm@latest

(Optional) The latest version of Typescript (version 4.1.2 or higher) is installed. To update Typescript, enter the following command.

$ npm install -g typescript@next

Installation

Step 1: Add the account linking reusable dialog as a dependency

To install the dependency using npm

$ npm i @alexa-skill-components/account-linking

To install the dependency using your package.json file

{
"dependencies":
{ "@alexa-skill-components/account-linking": "*" }
}

The resulting package.json file might look similar to the following example.

{
  "types": "dist/index.d.ts",
  "files": [
    "dist/*",
    "interactionModels/*",
    "response/*",
    "build"
   ]
  "dependencies": {
    "@alexa-skill-components/account-linking": "*"
    "@aws-sdk/client-dynamodb": "^3.199.0",
    "@aws-sdk/util-dynamodb": "^3.199.0",
    "@types/node": "^18.8.4",
    "ask-sdk-core": "^2.10.1",
    "ask-sdk-model": "^1.39.0",
    "lodash": "^4.17.15",
    "uuid": "^8.3.2"  
   }
}

Step 2: Install account linking reusable dialog package dependencies

To install package dependencies

From the root of your skill package, run the following command.

$ npm install

Step 3: Invoke the reusable dialogs

To invoke the account linking reusable dialog in your skill

In your existing ACDL dialog, mark the point at which you want to validate account linking. To do so, supply a customized Alexa presentation language (APL) and APLA (APL-audio) prompt document that indicates how Alexa should respond if account linking is not set up or configured correctly. The following is an example prompt.

You need a ride hailer account to order a ride. Open the Alexa app and click the link to connect to your ride hailer account.

The following example is a reusable dialog associated with the ride hailer use case.

namespace com.example.skill.name

import com.amazon.alexa.accountlinking.required.validateAccountIsLinked
import prompts.AccountLinkingRequiredAPLAPrompt
import prompts.AccountLinkingRequiredAPLPrompt

dialog Nothing RideHailerDialog {
    sample {
        ...
        ...
        defResponse = MultiModalResponse {
            apla =  AccountLinkingRequiredAPLAPrompt,
            apl = AccountLinkingRequiredAPLPrompt
        }
        validateAccountIsLinked(defResponse)
        ...
        ...
    }
}

Step 4: Compile and deploy the skill

To compile your ACDL skill

From the root directory of your skill package, run the following command.

$ askx compile

To deploy your ACDL skill

From the root directory of your skill package, run the following command.

$ askx deploy

Step 5: Modify your AWS Lambda methods

To modify your AWS Lambda index.js file in Javascript

In your main AWS Lambda index file, import the GetAccountLinkingStatusHandler. The following example shows how to import @alexa-skill-components/account-linking.

const accountLinking = require('@alexa-skill-components/account-linking');

exports.handler = Alexa.SkillBuilders.custom()
.addRequestHandlers(
new accountLinking.GetAccountLinkingDetailsHandler(),
)
.lambda();

(Optional) To modify your AWS Lambda index.ts file in Typescript

In your index.ts file, use the following syntax to modify your AWS Lambda methods.

import { GetAccountLinkingDetailsHandler } from "@alexa-skill-components/account-linking"

exports.handler = Alexa.SkillBuilders.custom()
    .addRequestHandlers(
        new GetAccountLinkingDetailsHandler(),
        ....
    )
    .lambda();

Contributions

Amazon wants to continually improve the customer experience, and we welcome your candid feedback. Connect with us on our Slack channel to share your thoughts.

Check back here often to get the latest instance of the account linking reusable dialog skill component.

License

Copyright 2022 Amazon.com, Inc., or its affiliates. All rights reserved. You may not use this file except in compliance with the terms and conditions set forth in the accompanying LICENSE file. THESE MATERIALS ARE PROVIDED ON AN "AS IS" BASIS. AMAZON SPECIFICALLY DISCLAIMS, WITH RESPECT TO THESE MATERIALS, ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.

@alexa-skill-components/account-linking v0.0.4