├── .gitignore
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── NOTICE
├── README.md
├── ask-resources.json
├── instructions
├── cli.md
├── create-alexa-hosted-function.md
├── create-aws-hosted-function.md
├── customize-skill-content.md
├── setup-vui-alexa-hosted.md
├── setup-vui-aws-hosted.md
├── submit-for-certification.md
└── test-using-simulator.md
├── lambda
└── custom
│ ├── index.js
│ └── package.json
└── skill-package
├── interactionModels
└── custom
│ └── en-US.json
└── skill.json
/.gitignore:
--------------------------------------------------------------------------------
1 | lambda/custom/node_modules
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | ## Code of Conduct
2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
4 | opensource-codeofconduct@amazon.com with any additional questions or comments.
5 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing Guidelines
2 |
3 | Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
4 | documentation, we greatly value feedback and contributions from our community.
5 |
6 | Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
7 | information to effectively respond to your bug report or contribution.
8 |
9 |
10 | ## Reporting Bugs/Feature Requests
11 |
12 | We welcome you to use the GitHub issue tracker to report bugs or suggest features.
13 |
14 | When filing an issue, please check [existing open](https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons/issues), or [recently closed](https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20), issues to make sure somebody else hasn't already
15 | reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
16 |
17 | * A reproducible test case or series of steps
18 | * The version of our code being used
19 | * Any modifications you've made relevant to the bug
20 | * Anything unusual about your environment or deployment
21 |
22 |
23 | ## Contributing via Pull Requests
24 | Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
25 |
26 | 1. You are working against the latest source on the *master* branch.
27 | 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
28 | 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
29 |
30 | To send us a pull request, please:
31 |
32 | 1. Fork the repository.
33 | 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
34 | 3. Ensure local tests pass.
35 | 4. Commit to your fork using clear commit messages.
36 | 5. Send us a pull request, answering any default questions in the pull request interface.
37 | 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
38 |
39 | GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
40 | [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
41 |
42 |
43 | ## Finding contributions to work on
44 | Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels ((enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any ['help wanted'](https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons/labels/help%20wanted) issues is a great place to start.
45 |
46 |
47 | ## Code of Conduct
48 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
49 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
50 | opensource-codeofconduct@amazon.com with any additional questions or comments.
51 |
52 |
53 | ## Security issue notifications
54 | If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
55 |
56 |
57 | ## Licensing
58 |
59 | See the [LICENSE](https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons/blob/master/LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
60 |
61 | We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes.
62 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | Amazon Software License 1.0
2 |
3 | This Amazon Software License ("License") governs your use, reproduction, and
4 | distribution of the accompanying software as specified below.
5 |
6 | 1. Definitions
7 |
8 | "Licensor" means any person or entity that distributes its Work.
9 |
10 | "Software" means the original work of authorship made available under this
11 | License.
12 |
13 | "Work" means the Software and any additions to or derivative works of the
14 | Software that are made available under this License.
15 |
16 | The terms "reproduce," "reproduction," "derivative works," and
17 | "distribution" have the meaning as provided under U.S. copyright law;
18 | provided, however, that for the purposes of this License, derivative works
19 | shall not include works that remain separable from, or merely link (or bind
20 | by name) to the interfaces of, the Work.
21 |
22 | Works, including the Software, are "made available" under this License by
23 | including in or with the Work either (a) a copyright notice referencing the
24 | applicability of this License to the Work, or (b) a copy of this License.
25 |
26 | 2. License Grants
27 |
28 | 2.1 Copyright Grant. Subject to the terms and conditions of this License,
29 | each Licensor grants to you a perpetual, worldwide, non-exclusive,
30 | royalty-free, copyright license to reproduce, prepare derivative works of,
31 | publicly display, publicly perform, sublicense and distribute its Work and
32 | any resulting derivative works in any form.
33 |
34 | 2.2 Patent Grant. Subject to the terms and conditions of this License, each
35 | Licensor grants to you a perpetual, worldwide, non-exclusive, royalty-free
36 | patent license to make, have made, use, sell, offer for sale, import, and
37 | otherwise transfer its Work, in whole or in part. The foregoing license
38 | applies only to the patent claims licensable by Licensor that would be
39 | infringed by Licensor's Work (or portion thereof) individually and
40 | excluding any combinations with any other materials or technology.
41 |
42 | 3. Limitations
43 |
44 | 3.1 Redistribution. You may reproduce or distribute the Work only if
45 | (a) you do so under this License, (b) you include a complete copy of this
46 | License with your distribution, and (c) you retain without modification
47 | any copyright, patent, trademark, or attribution notices that are present
48 | in the Work.
49 |
50 | 3.2 Derivative Works. You may specify that additional or different terms
51 | apply to the use, reproduction, and distribution of your derivative works
52 | of the Work ("Your Terms") only if (a) Your Terms provide that the use
53 | limitation in Section 3.3 applies to your derivative works, and (b) you
54 | identify the specific derivative works that are subject to Your Terms.
55 | Notwithstanding Your Terms, this License (including the redistribution
56 | requirements in Section 3.1) will continue to apply to the Work itself.
57 |
58 | 3.3 Use Limitation. The Work and any derivative works thereof only may be
59 | used or intended for use with the web services, computing platforms or
60 | applications provided by Amazon.com, Inc. or its affiliates, including
61 | Amazon Web Services, Inc.
62 |
63 | 3.4 Patent Claims. If you bring or threaten to bring a patent claim against
64 | any Licensor (including any claim, cross-claim or counterclaim in a
65 | lawsuit) to enforce any patents that you allege are infringed by any Work,
66 | then your rights under this License from such Licensor (including the
67 | grants in Sections 2.1 and 2.2) will terminate immediately.
68 |
69 | 3.5 Trademarks. This License does not grant any rights to use any
70 | Licensor's or its affiliates' names, logos, or trademarks, except as
71 | necessary to reproduce the notices described in this License.
72 |
73 | 3.6 Termination. If you violate any term of this License, then your rights
74 | under this License (including the grants in Sections 2.1 and 2.2) will
75 | terminate immediately.
76 |
77 | 4. Disclaimer of Warranty.
78 |
79 | THE WORK IS PROVIDED "AS IS" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
80 | EITHER EXPRESS OR IMPLIED, INCLUDING WARRANTIES OR CONDITIONS OF
81 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE OR
82 | NON-INFRINGEMENT. YOU BEAR THE RISK OF UNDERTAKING ANY ACTIVITIES UNDER
83 | THIS LICENSE. SOME STATES' CONSUMER LAWS DO NOT ALLOW EXCLUSION OF AN
84 | IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT APPLY TO YOU.
85 |
86 | 5. Limitation of Liability.
87 |
88 | EXCEPT AS PROHIBITED BY APPLICABLE LAW, IN NO EVENT AND UNDER NO LEGAL
89 | THEORY, WHETHER IN TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE
90 | SHALL ANY LICENSOR BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY DIRECT,
91 | INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR
92 | RELATED TO THIS LICENSE, THE USE OR INABILITY TO USE THE WORK (INCLUDING
93 | BUT NOT LIMITED TO LOSS OF GOODWILL, BUSINESS INTERRUPTION, LOST PROFITS
94 | OR DATA, COMPUTER FAILURE OR MALFUNCTION, OR ANY OTHER COMM ERCIAL DAMAGES
95 | OR LOSSES), EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF
96 | SUCH DAMAGES.
--------------------------------------------------------------------------------
/NOTICE:
--------------------------------------------------------------------------------
1 | Skill Sample Nodejs Buttons Hellobuttons
2 | Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # ** This repository has been archived **
2 | This repository is still available as a point-in-time reference, but no further updates or support will be prioritized.
3 |
4 | 
5 |
6 | ## Hello Buttons Skill
7 |
8 | **Important: The Echo Buttons Skill API is in beta and is subject to change at any time without notice. We welcome your feedback.**
9 |
10 |
11 | These instructions show how to create a simple skill called Hello Buttons. This skill demonstrates how to send directives to, and receive events from, [Echo Buttons](https://www.amazon.com/Echo-Buttons-Alexa-Gadget-Pack/dp/B072C4KCQH).
12 |
13 | **Note:** Hello Buttons demonstrates how to use the [GameEngine](https://developer.amazon.com/docs/echo-button-skills/gameengine-interface-reference.html) and [GadgetController](https://developer.amazon.com/docs/echo-button-skills/gadgetcontroller-interface-reference.html) skill interfaces. It is not intended to be a comprehensive example. For an end-to-end skill, please refer to the [Color Changer sample](https://github.com/alexa/skill-sample-nodejs-buttons-colorchanger).
14 |
15 | This sample skill uses:
16 |
17 | * The [developer portal](https://developer.amazon.com/home.html) to configure the skill and specify the interaction model
18 | * Code written in [Node.js](https://nodejs.org/en/) javascript, and using the [Alexa Skills Kit (ASK) SDK for Node.js](https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs) library.
19 |
20 | ## Hello Buttons Skill Flow
21 | When the Hello Buttons skill begins, it will send [animation directives](https://developer.amazon.com/docs/echo-button-skills/control-echo-buttons.html#animate) for the three possible trigger events (`buttonDown`, `buttonUp` and `none`) to all the Echo Buttons. Alexa will then ask you to press the buttons, and an audio file will play.
22 |
23 | When you press a button, the skill will interrupt Alexa's speech. If the button that you pressed is not awake, the skill will initialize the button by sending animation directives for `buttonDown`, `buttonUp` and `none` to that button. This is different from the original `LaunchRequest` intent, which sent initialization directives to all buttons.
24 |
25 | If the pressed button wakes up, you will see a different color on `buttonDown` and `buttonUp` events, as well as a breathing animation for the `none` event. If you cancel the skill (for example, by saying "Alexa, cancel") or the Input Handler expires, the buttons will fade from white to black.
26 |
27 | ## Preparation
28 | Before you create the Hello Buttons skill, you must take the following steps:
29 |
30 | * **Create an Amazon developer account** If you don't already have an Amazon developer account, go to the [developer portal](https://developer.amazon.com/alexa/console/ask#/) and select **Sign In** in the upper right to create a free account.
31 |
32 | ## Recommended
33 | * **Get Echo Buttons** This skill works best with two [Echo Buttons](https://www.amazon.com/Echo-Buttons-Alexa-Gadget-Pack/dp/B072C4KCQH/), but you can also test using simulated buttons that will appear in the developer console.
34 |
35 | ## Optional
36 | * [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
37 | * [ASK CLI](https://developer.amazon.com/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html)
38 | * [Node.JS version 8+](https://nodejs.org/)
39 |
40 | ## Skill Architecture
41 | Each skill consists of two basic parts, a front end and a back end.
42 | The front end is the voice interface, or VUI.
43 | The voice interface is configured through the voice interaction model.
44 | The back end is where the logic of your skill resides.
45 |
46 | ## Three Options for Skill Setup
47 | There are a number of different ways for you to setup your skill, depending on your experience and what tools you have available.
48 |
49 | * If this is your first skill, try the [Alexa-Hosted backend instructions](./instructions/setup-vui-alexa-hosted.md) to get started quickly.
50 | * If you want to build a "classic" Alexa skill, and manage the backend resources in your own AWS account, you can follow the [AWS-Hosted instructions](./instructions/setup-vui-aws-hosted.md).
51 | * Developers with the [ASK Command Line Interface](https://developer.amazon.com/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html) configured may build the Alexa Hello Buttons skill from the command-line [instructions](./instructions/cli.md).
52 |
53 | ---
54 |
55 | ## Additional Resources
56 |
57 | ### Community
58 | * [Amazon Developer Forums](https://forums.developer.amazon.com/spaces/165/index.html) - Join the conversation!
59 | * [Hackster.io](https://www.hackster.io/amazon-alexa) - See what others are building with Alexa.
60 |
61 | ### Tutorials & Guides
62 | * [Voice Design Guide](https://developer.amazon.com/designing-for-voice/) - A great resource for learning conversational and voice user interface design.
63 | * [Codecademy: Learn Alexa](https://www.codecademy.com/learn/learn-alexa) - Learn how to build an Alexa Skill from within your browser with this beginner friendly tutorial on Codecademy!
64 |
65 | ### Documentation
66 | * [Official Alexa Skills Kit SDK for Node.js](http://alexa.design/node-sdk-docs) - The Official Node.js SDK Documentation
67 | * [Official Alexa Skills Kit Documentation](https://developer.amazon.com/docs/ask-overviews/build-skills-with-the-alexa-skills-kit.html) - Official Alexa Skills Kit Documentation
68 |
69 |
--------------------------------------------------------------------------------
/ask-resources.json:
--------------------------------------------------------------------------------
1 | {
2 | "askcliResourcesVersion": "2020-03-31",
3 | "profiles": {
4 | "default": {
5 | "skillMetadata": {
6 | "src": "./skill-package"
7 | },
8 | "code": {
9 | "default": {
10 | "src": "lambda/custom"
11 | }
12 | },
13 | "skillInfrastructure": {
14 | "userConfig": {
15 | "runtime": "nodejs10.x",
16 | "handler": "index.handler",
17 | "awsRegion": "us-east-1"
18 | },
19 | "type": "@ask-cli/lambda-deployer"
20 | }
21 | }
22 | }
23 | }
24 |
--------------------------------------------------------------------------------
/instructions/cli.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa Hello Buttons Skill
2 |
3 |
4 | ## Setup w/ ASK CLI
5 |
6 | ### About
7 | This readme assumes you have your developer environment ready to go and that you have some familiarity with CLI (Command Line Interface) Tools, [AWS](https://aws.amazon.com/), and the [ASK Developer Portal](https://developer.amazon.com/alexa-skills-kit?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Content&sc_detail=hello-buttons-nodejs-V2_CLI-1&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Content_hello-buttons-nodejs-V2_CLI-1_Convert_WW_beginnersdevs&sc_segment=beginnersdevs).
8 | ### Pre-requisites
9 |
10 | * Node.js (> v8)
11 | * Register for an [AWS Account](https://aws.amazon.com/)
12 | * Register for an [Amazon Developer Account](https://developer.amazon.com?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Content&sc_detail=hello-buttons-nodejs-V2_CLI-1&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Content_hello-buttons-nodejs-V2_CLI-1_Convert_WW_beginnersdevs&sc_segment=beginnersdevs)
13 | * Install and initialize the [ASK CLI](https://developer.amazon.com/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Content&sc_detail=hello-buttons-nodejs-V2_CLI-1&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Content_hello-buttons-nodejs-V2_CLI-1_Convert_WW_beginnersdevs&sc_segment=beginnersdevs)
14 |
15 | > Note: If you would like to setup the ASK CLI using AWS Cloud9 (a cloud-based IDE with pay-as-you-go pricing and is eligible for AWS Free Tier pricing), step-by-step instructions can be found [here](https://alexa.design/cli-on-cloud9).
16 |
17 | ### Installation
18 | 1. **Make sure** you are running the latest version of the CLI
19 |
20 | ```bash
21 | npm update -g ask-cli
22 | ```
23 |
24 | 2. **Create** the skill based on the repository.
25 |
26 | ```bash
27 | ask new --url https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons.git --skill-name hello-buttons
28 | ```
29 |
30 | ### Deployment
31 |
32 | ASK CLI **will create the skill and the Lambda function for you**. The Lambda function will be created in ```us-east-1 (Northern Virginia)``` by default.
33 |
34 | 1. Navigate to the project's root directory. you should see a file named 'skill.json' there.
35 | 2. Deploy the skill and the Lambda function in one step by running the following command:
36 |
37 | ```bash
38 | ask deploy
39 | ```
40 |
41 | ### Testing
42 |
43 | 1. To test, the skill needs to be enabled. From the developer console, open your skill and click the Test tab. Ensure the skill is available for testing in Development.
44 |
45 | 2. Simulate verbal interaction with your skill through the command line (this might take a few moments) using the following example:
46 |
47 | ```bash
48 | ask simulate -l en-US -t "start Hello Buttons"
49 |
50 | ✓ Simulation created for simulation id: 4a7a9ed8-94b2-40c0-b3bd-fb63d9887fa7
51 | ◡ Waiting for simulation response{
52 | "status": "SUCCESSFUL",
53 | ...
54 | ```
55 |
56 | ## Additional Testing Options
57 | [](./test-using-simulator.md)
58 |
59 |
60 |
--------------------------------------------------------------------------------
/instructions/create-alexa-hosted-function.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa-Hosted Hello Buttons Skill
2 |
3 |
4 |
5 | ### Deploying Skill Code
6 |
7 | In the [first step of this guide](./setup-vui-alexa-hosted.md), we built the Voice User Interface (VUI) for our Alexa skill.
8 | On this page, we will be exploring the Alexa-Hosted code editor, and deploying our code to enable testing.
9 |
10 | * *For details on what the Alexa-Hosted skills service provides, open [this page](https://developer.amazon.com/docs/hosted-skills/build-a-skill-end-to-end-using-an-alexa-hosted-skill.html) in a new tab.*
11 |
12 | 1. Within your skill in the developer console, click to the Code tab at the top of the page.
13 | You should see folders and files within the left panel, and the **index.js** file opened in the main panel. This index.js file is the main code file for the skill.
14 | There is also a file called **package.json**. We will be updating both these files next.
15 |
16 | 2. Click into the index.js file, Select-All the code, and delete it.
17 |
18 | 3. From the Github project folders (above), locate and open the file [/lambda/custom/index.js](../lambda/custom/index.js).
19 |
20 | 4. Click the "Raw" button just above the code, and Select-All and copy the code. Return to the Alexa skill console and paste this into the index.js file you had previously cleared.
21 |
22 | 5. Repeat these steps for the **package.json** file: Copy the contents of [/lambda/custom/package.json](../lambda/custom/package.json), and paste them over the package.json file in your skill.
23 |
24 | 6. Select the Save button, then select Deploy. This will deploy your code into a Lambda function that is automatically managed for you by the Alexa-Hosted service.
25 |
26 | 7. At the bottom left corner of the page, notice the link to **Logs: Amazon CloudWatch**. CloudWatch is the logging service.
27 |
28 | * **Click the "Next" button to continue.**
29 |
30 | [](./test-using-simulator.md)
31 |
32 |
33 |
--------------------------------------------------------------------------------
/instructions/create-aws-hosted-function.md:
--------------------------------------------------------------------------------
1 | # Build An AWS-Hosted Hello Buttons Skill
2 |
3 |
4 | ## Setting Up A Lambda Function Using Amazon Web Services
5 |
6 | Before you create your back-end function, you will need:
7 |
8 | * **An AWS Account** If you haven't already, sign up for AWS by going to [AWS Free Tier](https://aws.amazon.com/free/). For most developers, the [AWS Lambda Free Tier](https://aws.amazon.com/lambda/pricing/) is sufficient for the function that supports an Alexa skill.
9 | * [GIT](https://git-scm.com/)
10 | * [Node.JS](https://nodejs.org) version 8 or higher
11 |
12 |
13 | ## Step 1: Create the Deployment Package
14 |
15 | 1. Clone the repository.
16 | Open a (bash) command prompt, or terminal, on your laptop, and run:
17 |
18 | ```bash
19 | $ git clone https://github.com/alexa/skill-sample-nodejs-buttons-hellobuttons/
20 | ```
21 |
22 | 2. Install npm dependencies by running the npm command `npm install` from the directory of the repo you just cloned in the previous step.
23 |
24 | ```bash
25 | $ cd skill-sample-nodejs-buttons-hellobuttons/lambda/custom
26 | $ npm install
27 | ```
28 |
29 | 3. Create an archive to upload to AWS Lambda.
30 |
31 | Make sure to execute the following in the `lambda/custom` directory:
32 |
33 | ```bash
34 | $ zip -r -X ../HelloButtonsDeploymentPackage.zip *
35 | ```
36 |
37 | ## Step 2: Upload the Deployment Package
38 | In this step, you upload the zip archive of the skill code and supporting modules to AWS Lambda. Later, when you set up the skill in the developer portal, you will specify that this function is the endpoint for the skill.
39 |
40 | 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/console/home?region=us-east-1#) and navigate to the [AWS Lambda console](https://console.aws.amazon.com/lambda/home?region=us-east-1), which is located under **Compute** services.
41 | 2. Using the region selector at the top right of the page, select **US East (N.Virginia)**.
42 | 3. Select **Create function**.
43 | 4. Select **Author from scratch**.
44 | 5. For **Name**, enter `HelloButtons`.
45 | 6. For **Runtime**, select **Node.js 8.10**.
46 | 7. For **Role**, select **Create new role from template(s)**.
47 | 8. For **Role name**, enter `HelloButtonsRole`.
48 | 9. From the **Policy templates** list, select **Simple Microservice permissions**.
49 | 10. In the lower right, click the **Create function** button. The function might take a moment to create.
50 | 11. Under the **Function code** section, for **Code entry type**, select **Upload a .ZIP file**. Then click **Upload** and choose the ``HelloButtonsDeploymentPackage.zip`` file.
51 | 12. For **Runtime**, select **Node.js 8.10**.
52 | 13. Under the **Designer** section, under **Add triggers**, select the **Alexa Skills Kit** option, select
53 | **Disable** under **Skill ID verification** and then select the **Add** button in the lower right.
54 | 14. (Optional, but recommended) To **secure this Lambda function** follow the instructions found here: [alexa.design/secure-lambda-function](https://alexa.design/secure-lambda-function)
55 |
56 | 15. At the top of the page, select **Save**.
57 |
58 | ## Step 3: Find the ARN of the Lambda function
59 | In this step, you find the Amazon Resource Name (ARN) of the Lambda function that you just created. The ARN serves as the ID of the function. You can find the ARN at the top right of the Hello Buttons function page in the AWS Lambda console. The ARN will look something
60 | like `arn:aws:lambda:us-east-1:012345678910:function:HelloButtons`.
61 |
62 | Copy the ARN. Later, when you set up the Hello Buttons skill in the developer portal, you will provide this ARN as the endpoint for the skill.
63 |
64 |
65 | * **Click the "Next" button to continue.**
66 |
67 | [](./test-using-simulator.md)
68 |
69 |
70 |
--------------------------------------------------------------------------------
/instructions/customize-skill-content.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa Buttons Skill
2 |
3 |
4 |
5 | ## Customize the Skill to be Yours
6 |
7 | At this point, you should have a working copy of our Hello Buttons skill.
8 | You may modify the code in the ```index.js```.
9 | For example, locate the line with the response: "Welcome to the Echo Buttons Test Skill.".
10 | Change this to a custom message, and save your code. Then, test your skill again and you should hear a new response.
11 |
12 | Normally, you would consider submitting your skill for certification. But, a default "hello world" skill is too simple to provide a valuable end user experience.
13 |
14 | Once you have created a good custom skill and are ready to publish, click to the "Distribution" then "Certification" tabs in the top navigation to advance.
15 |
16 |
17 | ### Reference Skills
18 |
19 | * [Color Changer](https://github.com/alexa/skill-sample-nodejs-buttons-colorchanger) - an end-to-end buttons example skill.
20 | * [Buttons Trivia](https://github.com/alexa/skill-sample-nodejs-buttons-trivia) - a trivia game which uses buttons.
21 | * [Fact Skill](https://github.com/alexa/skill-sample-nodejs-fact) - the Fact skill is a simple example a great next step after Hello World. The skill speaks facts to the user.
22 |
23 | [](./submit-for-certification.md)
24 |
--------------------------------------------------------------------------------
/instructions/setup-vui-alexa-hosted.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa-Hosted Hello Buttons Skill
2 |
3 |
4 |
5 | With an Alexa-hosted skill, you can build, edit, and publish a skill without leaving the developer console.
6 | The skill includes a code editor for managing and deploying the backend code for your skill.
7 | For details on what the Alexa-Hosted skills service provides, open [this page](https://developer.amazon.com/docs/hosted-skills/build-a-skill-end-to-end-using-an-alexa-hosted-skill.html) in a new tab.
8 |
9 | ### Steps
10 | 1. **Go to the [Amazon Developer Portal](http://developer.amazon.com/alexa?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=hello-buttons-nodejs-V2_GUI-1&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-1_Convert_WW_beginnersdevs&sc_segment=beginnersdevs). In the top-right corner of the screen, click the "Sign In" button.**
11 | (If you don't already have an account, you will be able to create a new one for free.)
12 |
13 | 2. Once you have signed in, move your mouse over the **Your Alexa Consoles** text at the top of the screen and Select the **Skills** Link.
14 |
15 | 3. From the **Alexa Skills Console** select the **Create Skill** button near the top-right of the list of your Alexa Skills.
16 |
17 | 4. Give your new skill a Name, such as **Hello Buttons**. This is the name that will be shown in the Alexa Skills Store, and the name your users will refer to. Also change the locale if so desired.
18 |
19 | 5. Keep the default **Custom** model selected, and scroll the page down.
20 |
21 | 6. Choose **Alexa-Hosted** for the method to host your skill's backend resources. Scroll backup and select the **Create Skill** button at the top right.
22 | It will take a minute to create your Alexa hosted skill, then you will be taken to the Build tab of the console.
23 |
24 | 7. On the Choose a template page, keep the default **Start from scratch** and click the **Choose** button.
25 |
26 | 8. **Build the Interaction Model for your skill**
27 | 1. If you want to change the skill invocation name, select the **Invocation** tab. Enter a **Skill Invocation Name**. This is the name that your users will need to say to start your skill.
28 | 2. Click "Build Model".
29 |
30 | 9. If your interaction model builds successfully, proceed to the next step. If not, you should see an error.
31 | Try to resolve the errors. In our next step of this guide, we will be creating our code.
32 |
33 | If you get an error from your interaction model, check through this list:
34 |
35 | * **Did you copy & paste the provided code correctly?** Hint: use the Raw button when viewing files in GitHub
36 | * **Did you accidentally add any characters to the Interaction Model or Sample Utterances ?**
37 |
38 | #### NEXT: Review and Deploy the Alexa-Hosted Code
39 | [](./create-alexa-hosted-function.md)
40 |
41 |
--------------------------------------------------------------------------------
/instructions/setup-vui-aws-hosted.md:
--------------------------------------------------------------------------------
1 | # Build the AWS-Hosted Hello Buttons Skill
2 |
3 |
4 |
5 | ### Steps
6 | 1. **Go to the [Amazon Developer Portal](http://developer.amazon.com/alexa?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=hello-buttons-nodejs-V2_GUI-1&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-1_Convert_WW_beginnersdevs&sc_segment=beginnersdevs). In the top-right corner of the screen, click the "Sign In" button.**
7 | (If you don't already have an account, you will be able to create a new one for free.)
8 |
9 | 2. Once you have signed in, move your mouse over the **Your Alexa Consoles** text at the top of the screen and Select the **Skills** Link.
10 |
11 | 3. From the **Alexa Skills Console** select the **Create Skill** button near the top-right of the list of your Alexa Skills.
12 |
13 | 4. Give your new skill a Name, such as **Hello Buttons**. This is the name that will be shown in the Alexa Skills Store, and the name your users will refer to. Also change the locale if so desired.
14 |
15 | 5. Keep the default **Custom** model selected, and click the **Create skill** button on the top right.
16 |
17 | 6. On the Choose a template page, keep the default **Start from scratch** and click the **Choose** button.
18 |
19 | 7. **Build the Interaction Model for your skill**
20 | 1. On the left hand navigation panel, select the **JSON Editor** tab under **Interaction Model**. In the textfield provided, replace any existing JSON with the JSON provided in the [Interaction Model](../models) (make sure to pick the model that matches your skill's language). Click **Save Model**.
21 | 2. If you want to change the skill invocation name, select the **Invocation** tab. Enter a **Skill Invocation Name**. This is the name that your users will need to say to start your skill.
22 | 3. Click "Build Model".
23 |
24 | 8. **Build the Interaction Model for your skill**
25 |
26 | 9. If your interaction model builds successfully, proceed to the next step. If not, you should see an error.
27 | Try to resolve the errors. In our next step of this guide, we will be creating our code.
28 |
29 | If you get an error from your interaction model, check through this list:
30 |
31 | * **Did you copy & paste the provided code correctly?** Hint: use the Raw button when viewing files in GitHub
32 | * **Did you accidentally add any characters to the Interaction Model or Sample Utterances ?**
33 |
34 | #### NEXT: Review and Deploy the AWS-Hosted Code
35 | [](./create-aws-hosted-function.md)
36 |
37 |
--------------------------------------------------------------------------------
/instructions/submit-for-certification.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa Buttons Skill
2 |
3 |
4 |
5 | ## Get Your Skill Certified and Published
6 |
7 | We are almost done! The last step is to add the metadata that your skill will use in the [Skill Store](http://amazon.com/skills). This page will walk you through the remaining steps to launch your skill!
8 |
9 | 1. Select the **Distribution** link from the top navigation menu.
10 |
11 | 2. Fill out the form fields per the guidance on the screen. Hover over the question mark icons for details regarding each respective field. **Fields marked with an Asterisk, are required!**
12 | * Take the time to get these right so that your skill will pass certification!
13 |
14 | 3. **Write your skill descriptions.**
15 |
16 | * **Spend some time coming up with an enticing, succinct description.** This is one of the few places you have an opportunity to attract new users, so make the most of it! These descriptions show up in the list of skills available in the [Alexa app](http://alexa.amazon.com/spa/index.html#skills) and the [skills store](http://www.amazon.com/skills).
17 |
18 | 4. For your example phrases, **come up with the three most exciting ways** a user can talk to your skill.
19 |
20 | * Make sure that each of your example phrases are a **perfect match with one of your Sample Utterances.** Incorrect example phrases are one of the most common reasons that skills fail certification, so we have provided a short list of things to consider as you write your example phrases:
21 |
22 | | Common Failure Points for Example Phrases |
23 | | ----------------------------------------- |
24 | | Example phrases **must** adhere to the [supported phrases](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/supported-phrases-to-begin-a-conversation?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs). |
25 | | Example phrases **must** be based on sample utterances specified in your Intent Schema. |
26 | | Your first example phrase **must** include a wake word and your invocation name. |
27 | | Example phrases **must** provide a contextual response. |
28 |
29 | * **Choose three example phrases that are likely to be the most common ways that users will attempt to interact with your skill.** Make sure that each of them works well, and provides an excellent user experience.
30 |
31 | 5. **Create your skill's icons.** You need two sizes of your icon: 108x108px and 512x512px. When you upload an image, it will be automatically fit to the required dimensions.
32 |
33 | * **Make sure you have the rights to the icons you create.** Please don't violate any trademarks or copyrights.
34 | * **If you don't have software to make icons, try one of these free options:**
35 |
36 | * [Alexa Skill Icon Builder](https://developer.amazon.com/docs/tools/icon-builder.html) (a link to this is included in the console)
37 |
38 | * [GIMP](https://www.gimp.org/) (Windows/Mac/Linux)
39 | * [Canva](https://www.canva.com/) (Web)
40 | * [Paint.NET](http://www.getpaint.net/index.html) (Windows)
41 | * [Inkscape](http://inkscape.org) (Windows/Mac/Linux)
42 | * [Iconion](http://iconion.com/) (Windows/Mac)
43 |
44 | * To make it easier to get started, we've created blank versions of these icons in both sizes for many formats:
45 |
46 | * [PSD](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/psd._TTH_.zip)
47 | * [PNG](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/png._TTH_.zip)
48 | * [GIF](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/gif._TTH_.zip)
49 | * [PDF](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/pdf._TTH_.zip)
50 | * [JPG](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/jpg._TTH_.zip)
51 | * [SVG](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/svg._TTH_.zip)
52 | * [PDN](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/pdn._TTH_.zip) - for [Paint.NET](http://www.getpaint.net/index.html)
53 | * [XCF](https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/general/icon-templates/xcf._TTH_.zip) - for [GIMP](https://www.gimp.org/)
54 |
55 | 6. Choose the most appropriate category for your skill.
56 |
57 | 7. **Provide a comprehensive list of keywords for users that are searching for new skills.** This is an optional field, and searching the [Alexa app](http://alexa.amazon.com) or the [skill store](http://www.amazon.com/skills) will also find the words in your Skill Name and descriptions, so you don't need to overdo it. That being said, if there are words that you want users to find your skill with, you should include them here. Separate the keywords with commas.
58 |
59 | 8. **Privacy Policy URL.** This is an optional field, and should not be required for this fact skill sample. You can leave it blank.
60 |
61 | 9. **Terms of Use URL.** This is also optional, and you can leave it blank.
62 |
63 | 10. When you're ready, click **Save and Continue** at the bottom of the screen to move onto **Privacy & Compliance**
64 |
65 | 11. * **Does this skill allow users to make purchases or spend real money?** For this fact skill, the answer is no. For future skills, make sure you answer this appropriately.
66 |
67 | * **Does this Alexa skill collect users' personal information?** Again, for this fact skill, the answer is no. If you do collect information about a user, such as names, email addresses, phone numbers, and so forth, ensure that you answer Yes to this question.
68 | * Answering "yes" to this question will also require you to provide a link to your Privacy Policy on the previous page.
69 |
70 | * **Is your skill directed to children under the age of 13?** Because you customized this skill with data you provided, it is possible that you created a skill that targets children under the age of 13. For this fact skill, the answer is **no** because it doesn't target a specific age group.
71 | * Factors to consider in determining if this skill is directed to children under 13 include:
72 | * Subject matter of the skill
73 | * Presence of child-oriented activities and incentives
74 | * Type of language used in the skill
75 | * Music and other audio content in the skill
76 | * How the skill is described and marketed
77 | * Intended audience for the skill
78 |
79 | If you're not sure, please see the [FTC's COPPA Guidance and FAQ](https://www.ftc.gov/tips-advice/business-center/guidance/complying-coppa-frequently-asked-questions) for more information.
80 |
81 | 12. **Export Compliance.** Be certain that you agree with all of the conditions. If you do, make sure to check this box, as Amazon requires this permission to distribute your skill around the globe.
82 |
83 | 13. **Provide testing instructions.** Testing instructions give you an opportunity to explain your skill, and any special or possibly confusing features, to the certification team. A value is required in this box.
84 |
85 | * Since you are using our Sample, make sure to add a sentence to your Testing Instructions referencing the Sample you used. For example:
86 |
87 | ```text
88 | This was built using the Fact Sample.
89 | ```
90 |
91 | This will let the testing team understand what you're providing them, and should decrease the testing time required.
92 |
93 | **Note:** More details on certification are [available here.](https://alexa.design/certification)
94 |
95 | 1. Click the **Save and Continue** button at the bottom of the page to move on to **Availability**.
96 | * You'll want to allow the Public to access the skill unless you are using [Alexa for Business](https://aws.amazon.com/a4b).
97 | * Beta testing is a good idea for every skill, however since this is from a template and is very basic, we'll skip that for now. When you make your next skill, don't skip this step. Seriously. You won't regret it.
98 | * It is recommended to allow your skill to be available in all countries and regions where Amazon distributes skills, unless you are using facts which aren't applicable to a given area. Reasons to restrict distribution include not having intellectual property rights to distribute to that area and the content being illegal, offensive or otherwise prohibited in that area.
99 |
100 | 1. If you feel that your skill is ready for certification, click the **Save and Continue** button at the bottom of the page and you'll be taken to the certification tab.
101 |
102 | 1. The **Validation** page will tell you if you have missed any steps along the way which will prevent your skill from being submitted. You shouldn't see anything on this page, but if you do, go back and fix the issues.
103 |
104 | 1. Click on the **Functional test** section and click the **Run** button to run functional tests against your skill. You shouldn't see any errors on this page, but if you do, go back and fix the issues.
105 |
106 | 1. Click on **Submission**, and the click **Submit for Review**.
107 |
108 | 15. **You're done with your submission!** Here are a few things you might need to know:
109 |
110 | * **Certification can take several days to complete.** Please be patient. It takes time because we want to get it right.
111 |
112 | * **Did something go wrong?** Our team of evangelists run [online office hours every Tuesday from 1-2pm Pacific Time](https://alexa.design/officehours). They can help answer any questions you might have.
113 |
114 | * **Want the coolest t-shirt you've ever seen?** Every month, we create a brand-new Alexa Developer t-shirt or hoodie, and send them out to developers that published a skill that month. [You can get yours here if you live in the US](https://developer.amazon.com/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), [here for the UK](https://developer.amazon.com/en-gb/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), [here for Germany](https://developer.amazon.com/de-de/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), [here for India](https://developer.amazon.com/alexa-skills-kit/alexa-developer-skill-promotion-india?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), [here for Japan](https://developer.amazon.com/ja/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), [here for France](https://developer.amazon.com/fr/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs), and [here for Australia](https://developer.amazon.com/anz/alexa-skills-kit/alexa-developer-skill-promotion?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=fact-nodejs-V2_GUI-6&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_fact-nodejs-V2_GUI-6_Convert_WW_beginnersdevs&sc_segment=beginnersdevs).
115 |
--------------------------------------------------------------------------------
/instructions/test-using-simulator.md:
--------------------------------------------------------------------------------
1 | # Build An Alexa Hello Buttons Skill
2 |
3 |
4 |
5 | ## Testing Your Skill with the Alexa Simulator
6 |
7 | So far, we have created a Voice User Interface, and deployed code to a backend service linked to the skill. Your skill is now ready to test.
8 |
9 | 1. If you are not continuing immediately from the previous step, **go back to the [Amazon Developer Portal](https://developer.amazon.com/alexa/console/ask?&sc_category=Owned&sc_channel=RD&sc_campaign=Evangelism2018&sc_publisher=github&sc_content=Survey&sc_detail=hello-buttons-nodejs-V2_GUI-4&sc_funnel=Convert&sc_country=WW&sc_medium=Owned_RD_Evangelism2018_github_Survey_hello-buttons-nodejs-V2_GUI-4_Convert_WW_beginnersdevs&sc_segment=beginnersdevs) and select your skill from the list.**
10 |
11 | 2. Access the **Alexa Simulator**, by selecting the **Test** tab from the top navigation menu. Your browser may request permission to access your microphone. While it is recommended to do so, it is not required. Do note that if you don't allow access to the microphone, you must type your utterances to Alexa in the simulator.
12 |
13 | 3. Notice the dropdown labeled "Skill testing is enabled in:", found just underneath the top navigation menu.
14 | Toggle the dropdown from **Off** to **Development**.
15 |
16 | 4. To validate that your skill is working as expected, invoke your skill from the **Alexa Simulator** just below. You can either type or click and hold the mic from the input box to use your voice.
17 | 1. **Type** "Open" followed by the invocation name you gave your skill previously. For example, "Open hello world".
18 | 2. **Use your voice** by clicking and holding the mic on the side panel and saying "Open" followed by the invocation name you gave your skill.
19 | 3. **If you've forgotten the invocation name** for your skill, revisit the **Build** panel on the top navigation menu and select **Invocation** from the sidebar to review it.
20 |
21 | * *Tip: Always finish your test by saying "stop" to formally end your session.*
22 |
23 | 5. Notice the four buttons that appear in the test console. Click each of them to simulate button press events. You should hear your skill respond.
24 |
25 | 6. Ensure your skill works the way that you designed it to.
26 | * After you interact with the Alexa Simulator, you should see the Skill I/O **JSON Input** and **JSON Output** boxes get populated with JSON data. You can also view the **Device Log** to trace your steps.
27 | * If it's not working as expected, you can dig into the JSON to see exactly what Alexa is sending and receiving from the endpoint. If something is broken, you can find the error in AWS Cloudwatch.
28 |
29 | 7. Troubleshooting with CloudWatch log messages: You can add console.log() statements to your code, to track what is happening as your code executes, and help to figure out what is happening when something goes wrong.
30 | You will find the log to be incredibly valuable as you move into more advanced skills.
31 |
32 |
33 | ## Testing with Devices
34 | 1. Make sure your [Echo Buttons](https://www.amazon.com/gp/help/customer/display.html?nodeId=G202211490) have batteries.
35 | 1. Say "Alexa, set up my echo button".
36 | 1. Alexa will walk you through the [Pair Button](https://www.amazon.com/gp/help/customer/display.html?nodeId=G202211490) steps. The button will link over bluetooth.
37 | 1. Repeat for remaining buttons.
38 | 1. Invoke the skill and try using the buttons.
39 |
40 |
41 | ## Review Skill Flow
42 | * Click back home to [README.md](../README.md) and review that ths skill runs as described in the Skill Flow.
43 |
44 | [](./customize-skill-content.md)
45 |
--------------------------------------------------------------------------------
/lambda/custom/index.js:
--------------------------------------------------------------------------------
1 | /**
2 | Copyright 2018 Amazon.com, Inc. and its affiliates. All Rights Reserved.
3 | Licensed under the Amazon Software License (the "License").
4 | You may not use this file except in compliance with the License.
5 | A copy of the License is located at
6 | http://aws.amazon.com/asl/
7 | or in the "license" file accompanying this file. This file is distributed
8 | on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express
9 | or implied. See the License for the specific language governing
10 | permissions and limitations under the License.
11 |
12 | This sample skill opens with buttons roll call and asks the user to
13 | push two buttons. On button one press, she changes the color to red and on
14 | button two press she changes the color to blue. Then closes. This Skill
15 | demonstrates how to send directives to, and receive events from, Echo Buttons.
16 | **/
17 |
18 |
19 | 'use strict';
20 |
21 | const Alexa = require('ask-sdk-core');
22 |
23 | let skill;
24 | exports.handler = function (event, context) {
25 | // Prints Alexa Event Request to CloudWatch logs for easier debugging
26 | console.log(`===EVENT===${JSON.stringify(event)}`);
27 | if (!skill) {
28 | skill = Alexa.SkillBuilders.custom()
29 | .addRequestHandlers(
30 | main.LaunchRequestHandler,
31 | main.GameEngineInputHandler,
32 | main.HelpIntentHandler,
33 | main.StopAndCancelIntentHandler,
34 | main.SessionEndedRequestHandler,
35 | main.FallbackHandler,
36 | main.DefaultHandler
37 | )
38 | .addResponseInterceptors(main.ResponseInterceptor)
39 | .addErrorHandlers(main.ErrorHandler)
40 | .create();
41 | }
42 |
43 | return skill.invoke(event,context);
44 | };
45 |
46 | const main = {
47 | LaunchRequestHandler: {
48 | canHandle(handlerInput) {
49 | let { request } = handlerInput.requestEnvelope;
50 | console.log("LaunchRequestHandler: checking if it can handle " + request.type);
51 | return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
52 | },
53 | handle(handlerInput) {
54 | console.log("LaunchRequestHandler: handling request");
55 |
56 | const { attributesManager, requestEnvelope } = handlerInput;
57 | const sessionAttributes = attributesManager.getSessionAttributes();
58 |
59 | // Build a basic response and have Alexa say something in the standard way.
60 | let response = handlerInput.responseBuilder
61 | .speak("Welcome to the Buttons Test Skill. " +
62 | "Press your Echo Buttons to change the colors of the lights. " +
63 | "")
64 | .getResponse();
65 |
66 | response.directives = response.directives || [];
67 |
68 | /*
69 | On launch, this skill will immediately set up the InputHandler to
70 | listen to all attached buttons for 30 seconds.
71 | The Skill will then set up two events that each report when buttons are
72 | pressed and when they're released.
73 | After 30 seconds, the Skill will receive the timeout event.
74 | For more details on InputHandlers, see
75 | https://developer.amazon.com/docs/echo-button-skills/define-echo-button-events.html
76 | */
77 | response.directives.push(buttonStartInputHandlerDirective);
78 |
79 | // Start keeping track of some state.
80 | sessionAttributes.buttonCount = 0;
81 | /*
82 | Preserve the originatingRequestId. We'll use this to stop the
83 | InputHandler later.
84 | See the Note at https://developer.amazon.com/docs/echo-button-skills/receive-echo-button-events.html#start
85 | */
86 | sessionAttributes.CurrentInputHandlerID = requestEnvelope.request.requestId;
87 |
88 | /*
89 | If the buttons are awake before the Skill starts, the Skill can send
90 | animations to all of the buttons by targeting the empty array [].
91 | */
92 | // Build the breathing animation that will play immediately.
93 | response.directives.push(buildButtonIdleAnimationDirective([], breathAnimationRed));
94 |
95 | // Build the 'button down' animation for when the button is pressed.
96 | response.directives.push(buildButtonDownAnimationDirective([]));
97 |
98 | // Build the 'button up' animation for when the button is released.
99 | response.directives.push(buildButtonUpAnimationDirective([]));
100 |
101 | /*
102 | Deleting `shouldEndSession` will keep the session open, but NOT open
103 | the microphone.
104 | You could also set `shouldEndSession` to false if you also wanted a
105 | voice intent.
106 | Never set `shouldEndSession` to true if you're expecting InputHandler
107 | events Because you'll lose the session!
108 | See https://developer.amazon.com/docs/echo-button-skills/receive-voice-input.html#types
109 | */
110 | delete response.shouldEndSession;
111 |
112 | return response;
113 | }
114 | },
115 | ErrorHandler: {
116 | canHandle(handlerInput, error) {
117 | let { request } = handlerInput.requestEnvelope;
118 | console.log("main.ErrorHandler: checking if it can handle "
119 | + request.type + ": [" + error.name + "] -> " + !!error.name);
120 | return !!error.name; //error.name.startsWith('AskSdk');
121 | },
122 | handle(handlerInput, error) {
123 | console.log("Global.ErrorHandler: error = " + error.message);
124 |
125 | return handlerInput.responseBuilder
126 | .speak("I'm sorry, something went wrong!")
127 | .getResponse();
128 | }
129 | },
130 | HelpIntentHandler: {
131 | canHandle(handlerInput) {
132 | const { request } = handlerInput.requestEnvelope;
133 | const intentName = request.intent ? request.intent.name : '';
134 | console.log("main.HelpIntentHandler: checking if it can handle "
135 | + request.type + " for " + intentName);
136 | return request.type === 'IntentRequest'
137 | && intentName === 'AMAZON.HelpIntent';
138 | },
139 | handle(handlerInput) {
140 | console.log("Global.HelpIntentHandler: handling request for help");
141 | var response = handlerInput.responseBuilder
142 | .speak("Welcome to the Buttons Test Skill. " +
143 | "Press your Echo Buttons to change the lights. " +
144 | "")
145 | .getResponse();
146 | delete response.shouldEndSession;
147 | return response;
148 | }
149 | },
150 | FallbackHandler: {
151 | canHandle(handlerInput) {
152 | const { request } = handlerInput.requestEnvelope;
153 | const intentName = request.intent ? request.intent.name : '';
154 | console.log("main.HelpIntentHandler: checking if it can handle "
155 | + request.type + " for " + intentName);
156 | return request.type === 'IntentRequest'
157 | && intentName === 'AMAZON.FallbackIntent';
158 | },
159 | handle(handlerInput) {
160 | console.log("Global.FallbackHandler: handling unknown request.");
161 | var response = handlerInput.responseBuilder
162 | .speak(`Sorry I did not get that, try again? `)
163 | .getResponse();
164 | delete response.shouldEndSession;
165 | return response;
166 | }
167 | },
168 | StopAndCancelIntentHandler: {
169 | canHandle(handlerInput) {
170 | const { request } = handlerInput.requestEnvelope;
171 | const intentName = request.intent ? request.intent.name : '';
172 | console.log("main.StopAndCancelIntentHandler: checking if it can handle "
173 | + request.type + " for " + intentName);
174 | return request.type === 'IntentRequest'
175 | && (intentName === 'AMAZON.StopIntent' || intentName === 'AMAZON.CancelIntent');
176 | },
177 | handle(handlerInput) {
178 | console.log("Global.HelpIntentHandler: handling request for help");
179 |
180 | const { attributesManager } = handlerInput;
181 | const sessionAttributes = attributesManager.getSessionAttributes();
182 |
183 | var response = handlerInput.responseBuilder
184 | .speak("Thank you for using the Gadgets Test Skill. Goodbye. ")
185 | .getResponse();
186 | if (sessionAttributes.CurrentInputHandlerID !== undefined) {
187 | response.directives = response.directives || [];
188 | response.directives.push(buttonStopInputHandlerDirective(sessionAttributes.CurrentInputHandlerID));
189 | }
190 | return response;
191 | }
192 | },
193 | DefaultHandler: {
194 | canHandle(handlerInput) {
195 | let { request } = handlerInput.requestEnvelope;
196 | let intentName = request.intent ? request.intent.name : '';
197 | console.log("main.DefaultHandler: checking if it can handle "
198 | + request.type + " for " + intentName);
199 | return true;
200 | },
201 | handle(handlerInput) {
202 | console.log("Global.DefaultHandler: handling request");
203 |
204 | var response = handlerInput.responseBuilder
205 | .speak("Sorry, I didn't get that. " +
206 | "Please press your Echo Buttons to change the color of the lights. " +
207 | "")
208 | .getResponse();
209 | delete response.shouldEndSession;
210 | return response;
211 | }
212 | },
213 | SessionEndedRequestHandler: {
214 | canHandle(handlerInput) {
215 | return handlerInput.requestEnvelope.request.type === 'SessionEndedRequest';
216 | },
217 | handle(handlerInput) {
218 | console.log(`Session ended with reason: ${handlerInput.requestEnvelope.request.reason}`);
219 | return handlerInput.responseBuilder.getResponse();
220 | },
221 | },
222 | GameEngineInputHandler: {
223 | canHandle(handlerInput) {
224 | let { request } = handlerInput.requestEnvelope;
225 | console.log("main.GameEngineInputHandler: checking if it can handle " + request.type);
226 | return request.type === 'GameEngine.InputHandlerEvent';
227 | },
228 | handle(handlerInput) {
229 | console.log('Received game event');
230 | let { attributesManager } = handlerInput;
231 | let request = handlerInput.requestEnvelope.request;
232 | const sessionAttributes = attributesManager.getSessionAttributes();
233 | if (request.originatingRequestId !== sessionAttributes.CurrentInputHandlerID) {
234 | console.log("Global.GameEngineInputHandler: stale input event received -> "
235 | +"received event from " + request.originatingRequestId
236 | +" (was expecting " + sessionAttributes.CurrentInputHandlerID + ")");
237 | return handlerInput.responseBuilder.getResponse();
238 | }
239 |
240 | var gameEngineEvents = request.events || [];
241 | for (var i = 0; i < gameEngineEvents.length; i++) {
242 | let buttonId;
243 |
244 | /*
245 | In this request type, we'll see one or more incoming events that
246 | correspond to the StartInputHandler directive we sent above.
247 | */
248 | switch (gameEngineEvents[i].name) {
249 | case 'button_down_event': {
250 |
251 | // ID of the button that triggered the event.
252 | buttonId = gameEngineEvents[i].inputEvents[0].gadgetId;
253 |
254 | // Recognize a new button.
255 | let isNewButton = false;
256 | if (sessionAttributes[buttonId + '_initialized'] === undefined) {
257 | isNewButton = true;
258 | sessionAttributes.buttonCount += 1;
259 |
260 | sessionAttributes[buttonId + '_initialized'] = true;
261 | }
262 |
263 | let response = handlerInput.responseBuilder.getResponse();
264 |
265 | if (isNewButton) {
266 | // Say something when we first encounter a button.
267 | response = handlerInput.responseBuilder
268 | .speak("Hello button " + sessionAttributes.buttonCount + ". " +
269 | "Good to see you." +
270 | "")
271 | .getResponse();
272 | response.directives = [];
273 | /*
274 | This is a new button, as in new to our understanding.
275 | Because this button may have just woken up, it may not have
276 | received the initial animations during the launch intent.
277 | We'll resend the animations here, but instead of the empty array
278 | broadcast above, we'll send the animations ONLY to this buttonId.
279 | */
280 | response.directives.push(buildButtonIdleAnimationDirective([buttonId], breathAnimationRed));
281 | response.directives.push(buildButtonDownAnimationDirective([buttonId]));
282 | response.directives.push(buildButtonUpAnimationDirective([buttonId]));
283 | }
284 |
285 | // Again, this means don't end the session, and don't open the microphone.
286 | delete response.shouldEndSession;
287 | return response;
288 | }
289 | case 'button_up_event': {
290 | buttonId = gameEngineEvents[i].inputEvents[0].gadgetId;
291 |
292 | /*
293 | On releasing the button, we'll replace the 'none' animation
294 | with a new color from a set of animations.
295 | */
296 | let newAnimationIndex = ((attributes, buttonId, maxLength) => {
297 | let index = 1;
298 |
299 | if (attributes[buttonId] !== undefined) {
300 | let newValue = attributes[buttonId] + 1;
301 | if (newValue >= maxLength) {
302 | newValue = 0;
303 | }
304 | index = newValue;
305 | }
306 |
307 | attributes[buttonId] = index;
308 |
309 | return index;
310 | })(sessionAttributes, buttonId, animations.length);
311 |
312 | let newAnimation = animations[newAnimationIndex];
313 |
314 | let response = handlerInput.responseBuilder.getResponse();
315 | response.directives = [buildButtonIdleAnimationDirective([buttonId], newAnimation)];
316 | delete response.shouldEndSession;
317 | return response;
318 | }
319 | case 'timeout': {
320 |
321 | // The timeout of our InputHandler was reached. Let's close the Skill session.
322 | if (sessionAttributes.buttonCount == 0) {
323 | return handlerInput.responseBuilder
324 | .speak("I didn't detect any buttons. " +
325 | "You must have at least one Echo Button to use this skill. Goodbye. ")
326 | .getResponse();
327 | } else {
328 | return handlerInput.responseBuilder
329 | .speak("Thank you for using the Gadgets Test Skill. Goodbye. ")
330 | .getResponse();
331 | }
332 | }
333 | }
334 | }
335 | }
336 | },
337 | ResponseInterceptor: {
338 | process(handlerInput) {
339 | /* a response interceptor alows us one more chance to process any response
340 | from the skill before sending it back to Alexa. In this interceptor we
341 | simplay log both the Response element as well as any SessionAttributes */
342 | let {attributesManager, responseBuilder} = handlerInput;
343 | console.log("main.ResponseInterceptor: post-processing response");
344 |
345 | let response = responseBuilder.getResponse();
346 |
347 | console.log(`==Response==${JSON.stringify(response)}`);
348 | console.log(`==SessionAttributes==${JSON.stringify(attributesManager.getSessionAttributes())}`);
349 |
350 | return response;
351 | }
352 | }
353 | };
354 |
355 | /*
356 | The following are animation generation functions that work with the
357 | hexadecimal format that SetLight expects.
358 | */
359 |
360 | const buildBreathAnimation = function(fromRgbHex, toRgbHex, steps, totalDuration) {
361 | const halfSteps = steps / 2;
362 | const halfTotalDuration = totalDuration / 2;
363 | return buildSeqentialAnimation(fromRgbHex, toRgbHex, halfSteps, halfTotalDuration)
364 | .concat(buildSeqentialAnimation(toRgbHex, fromRgbHex, halfSteps, halfTotalDuration));
365 | }
366 |
367 | const buildSeqentialAnimation = function(fromRgbHex, toRgbHex, steps, totalDuration) {
368 | const fromRgb = parseInt(fromRgbHex, 16);
369 | let fromRed = fromRgb >> 16;
370 | let fromGreen = (fromRgb & 0xff00) >> 8;
371 | let fromBlue = fromRgb & 0xff;
372 |
373 | const toRgb = parseInt(toRgbHex, 16);
374 | const toRed = toRgb >> 16;
375 | const toGreen = (toRgb & 0xff00) >> 8;
376 | const toBlue = toRgb & 0xff;
377 |
378 | const deltaRed = (toRed - fromRed) / steps;
379 | const deltaGreen = (toGreen - fromGreen) / steps;
380 | const deltaBlue = (toBlue - fromBlue) / steps;
381 |
382 | const oneStepDuration = Math.floor(totalDuration / steps);
383 |
384 | const result = [];
385 |
386 | for (let i = 0; i < steps; i++) {
387 | result.push({
388 | "durationMs": oneStepDuration,
389 | "color": rgb2h(fromRed, fromGreen, fromBlue),
390 | "blend": true
391 | });
392 | fromRed += deltaRed;
393 | fromGreen += deltaGreen;
394 | fromBlue += deltaBlue;
395 | }
396 |
397 | return result;
398 | }
399 |
400 | const rgb2h = function(r, g, b) {
401 | return '' + n2h(r) + n2h(g) + n2h(b);
402 | }
403 | // Number to hex with leading zeros.
404 | const n2h = function(n) {
405 | return ('00' + (Math.floor(n)).toString(16)).substr(-2);
406 | }
407 |
408 | const breathAnimationRed = buildBreathAnimation('552200', 'ff0000', 30, 1200);
409 | const breathAnimationGreen = buildBreathAnimation('004411', '00ff00', 30, 1200);
410 | const breathAnimationBlue = buildBreathAnimation('003366', '0000ff', 30, 1200);
411 | const animations = [breathAnimationRed, breathAnimationGreen, breathAnimationBlue];
412 |
413 | /*
414 | Build a 'button down' animation directive.
415 | The animation will overwrite the default 'button down' animation.
416 | */
417 | const buildButtonDownAnimationDirective = function(targetButtons) {
418 | return {
419 | "type": "GadgetController.SetLight",
420 | "version": 1,
421 | "targetGadgets": targetButtons,
422 | "parameters": {
423 | "animations": [{
424 | "repeat": 1,
425 | "targetLights": ["1"],
426 | "sequence": [{
427 | "durationMs": 300,
428 | "color": "FFFF00",
429 | "blend": false
430 | }]
431 | }],
432 | "triggerEvent": "buttonDown",
433 | "triggerEventTimeMs": 0
434 | }
435 | }
436 | };
437 |
438 | // Build a 'button up' animation directive.
439 | const buildButtonUpAnimationDirective = function(targetButtons) {
440 | return {
441 | "type": "GadgetController.SetLight",
442 | "version": 1,
443 | "targetGadgets": targetButtons,
444 | "parameters": {
445 | "animations": [{
446 | "repeat": 1,
447 | "targetLights": ["1"],
448 | "sequence": [{
449 | "durationMs": 300,
450 | "color": "00FFFF",
451 | "blend": false
452 | }]
453 | }],
454 | "triggerEvent": "buttonUp",
455 | "triggerEventTimeMs": 0
456 | }
457 | }
458 | };
459 |
460 | // Build an idle animation directive.
461 | const buildButtonIdleAnimationDirective = function(targetButtons, animation) {
462 | return {
463 | "type": "GadgetController.SetLight",
464 | "version": 1,
465 | "targetGadgets": targetButtons,
466 | "parameters": {
467 | "animations": [{
468 | "repeat": 100,
469 | "targetLights": ["1"],
470 | "sequence": animation
471 | }],
472 | "triggerEvent": "none",
473 | "triggerEventTimeMs": 0
474 | }
475 | }
476 | };
477 |
478 | const buttonStartInputHandlerDirective = {
479 | "type": "GameEngine.StartInputHandler",
480 | "timeout": 30000, // In milliseconds.
481 | "recognizers": { // Defines which Button Presses your Skill would like to receive as events.
482 | "button_down_recognizer": {
483 | "type": "match",
484 | "fuzzy": false,
485 | "anchor": "end",
486 | "pattern": [{
487 | "action": "down"
488 | }]
489 | },
490 | "button_up_recognizer": {
491 | "type": "match",
492 | "fuzzy": false,
493 | "anchor": "end",
494 | "pattern": [{
495 | "action": "up"
496 | }]
497 | }
498 | },
499 | "events": { // These events will be sent to your Skill in a request.
500 | "button_down_event": {
501 | "meets": ["button_down_recognizer"],
502 | "reports": "matches",
503 | "shouldEndInputHandler": false
504 | },
505 | "button_up_event": {
506 | "meets": ["button_up_recognizer"],
507 | "reports": "matches",
508 | "shouldEndInputHandler": false
509 | },
510 | "timeout": {
511 | "meets": ["timed out"],
512 | "reports": "history",
513 | "shouldEndInputHandler": true
514 | }
515 | }
516 | };
517 |
518 | /*
519 | Called when closing the Skill if an InputHandler is active. We can do this
520 | because we kept the requestId when we started this InputHandler. It's always
521 | a good idea to clean up when your Skill's session ends.
522 | */
523 | const buttonStopInputHandlerDirective = function(inputHandlerOriginatingRequestId) {
524 | return {
525 | "type": "GameEngine.StopInputHandler",
526 | "originatingRequestId": inputHandlerOriginatingRequestId
527 | }
528 | };
529 |
--------------------------------------------------------------------------------
/lambda/custom/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "skill-sample-nodejs-buttons-hellobuttons",
3 | "version": "1.0.0",
4 | "description": "An Echo Buttons sample skill.",
5 | "main": "index.js",
6 | "dependencies": {
7 | "ask-sdk-core": "^2.0.3",
8 | "ask-sdk-model": "^1.3.0"
9 | },
10 | "devDependencies": {},
11 | "scripts": {
12 | "test": "echo \"Error: no test specified\" && exit 1"
13 | },
14 | "keywords": [
15 | "alexa",
16 | "skill",
17 | "echo buttons"
18 | ],
19 | "author": "Amazon.com",
20 | "license": "Amazon-1.0"
21 | }
22 |
--------------------------------------------------------------------------------
/skill-package/interactionModels/custom/en-US.json:
--------------------------------------------------------------------------------
1 | {
2 | "interactionModel": {
3 | "languageModel": {
4 | "invocationName": "hello buttons",
5 | "intents": [
6 | {
7 | "name": "HelloIntent",
8 | "slots": [],
9 | "samples": [
10 | "hello"
11 | ]
12 | },
13 | {
14 | "name": "AMAZON.FallbackIntent",
15 | "samples": []
16 | },
17 | {
18 | "name": "AMAZON.CancelIntent",
19 | "samples": []
20 | },
21 | {
22 | "name": "AMAZON.HelpIntent",
23 | "samples": []
24 | },
25 | {
26 | "name": "AMAZON.StopIntent",
27 | "samples": []
28 | },
29 | {
30 | "name": "AMAZON.NavigateHomeIntent",
31 | "samples": []
32 | }
33 | ],
34 | "types": []
35 | }
36 | }
37 | }
--------------------------------------------------------------------------------
/skill-package/skill.json:
--------------------------------------------------------------------------------
1 | {
2 | "manifest": {
3 | "publishingInformation": {
4 | "locales": {
5 | "en-US": {
6 | "summary": "Hello Buttons",
7 | "examplePhrases": [
8 | "Alexa, open hello buttons",
9 | "Alexa, launch hello buttons"
10 | ],
11 | "keywords": [
12 | "Echo Buttons API",
13 | "Echo Buttons"
14 | ],
15 | "name": "hello buttons",
16 | "description": "This is an example skill to show how to use the Echo Buttons API"
17 | }
18 | },
19 | "isAvailableWorldwide": true,
20 | "testingInstructions": "Open the skill and press connected Echo Buttons to see lights animate",
21 | "category": "GAMES",
22 | "distributionCountries": [],
23 | "gadgetSupport": {
24 | "requirement": "REQUIRED",
25 | "numPlayersMin": 1,
26 | "numPlayersMax": 1,
27 | "minGadgetButtons": 1,
28 | "maxGadgetButtons": 4
29 | }
30 | },
31 | "apis": {
32 | "custom": {
33 | "interfaces": [
34 | {
35 | "type": "GAME_ENGINE"
36 | },
37 | {
38 | "type": "GADGET_CONTROLLER"
39 | }
40 | ]
41 | }
42 | },
43 | "manifestVersion": "1.0",
44 | "privacyAndCompliance": {
45 | "allowsPurchases": false,
46 | "usesPersonalInfo": false,
47 | "isChildDirected": false,
48 | "isExportCompliant": true,
49 | "containsAds": false
50 | }
51 | }
52 | }
53 |
--------------------------------------------------------------------------------