@alexa-skill-components/account-linking
v0.0.4
Published
Alexa skill component for verifying a account is linked
Downloads
9
Keywords
Readme
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.
Log in to the Alexa developer console, and make sure you meet the following other prerequisites.
- 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 updatenpm
, 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.