Alexa Blogs
Today’s post comes from J. Michael Palermo IV, Sr. Evangelist at Amazon Alexa. Learn what steps you should take before developing with the Smart Home Skill API.
Before creating a skill, you must first determine if you want to build a custom skill or a smart home skill. Most skills are built using the Alexa Skills Kit (ASK) and are broadly known as custom skills. However, if the end goal is to enable a skill to have voice control over a device or appliance in the home, you will want to develop a smart home skill using the Smart Home Skill API.
Smart home skills differ from custom skills in these ways:
- With custom skills, you must build a voice interaction model to handle customer requests. Smart home skills use Amazon’s standardized language model so you don’t have to build the voice interaction model. As such, your customers don’t need to remember your skill name or a specific invocation phrase. Furthermore, customers who already control devices using Alexa with other smart home skills already know how to use your smart home skill, and will also enjoy a consistent, first class experience with your devices.
- The smart home skill adapter must be hosted in an AWS Lambda function, whereas custom skills can be hosted in either AWS Lambda or another cloud-based hosting service.
- You must implement account linking using OAuth 2.0 for smart home skills, while this is optional for custom skills.
- Since smart home skills target connected devices in the home, you must have access to a cloud-based API to handle device discovery and control.
With the above differences in mind, your approach to creating a smart home skill may require more work to be done upfront than with a custom skill. However, know that with a smart home API skill, you wouldn’t need to define and maintain a language model yourself, and as Alexa improves its language model overall, you get the improvements for free.
Meeting the Smart Home Skill API Prerequisites, Step by Step
Follow these steps to confirm you have what you need before developing a smart home skill. Start by following these five steps to meet the Smart Home Skill API prerequisites:
- Choose OAuth 2.0 provider for account linking
- Initialize creation of smart home skill
- Create an AWS Lambda Function
- Configure smart home skill
- Finalize account linking and confirm
Step 1: Choose OAuth 2.0 Provider for Account Linking
Sebastien Stormacq recently authored an excellent blog post providing step-by-step guidance to implement account linking for custom skills. While much of the information in that post applies here too, there are some differences in implementation details. This post will provide complete guidance for setting up account linking for smart home skills, with some admitted overlap to Sebastien’s post. For a fine overview of OAuth 2.0 and understanding of options, it may benefit you to read the first two sections of his post and then resume here.
If you have already created or chosen a specific OAuth 2.0 provider, you can proceed to the next step. If not, the remainder of this step will show how to fulfill this requirement by using Login with Amazon (LWA).
First, you need to create an LWA security profile. Here’s how:
- Connect to https://developer.amazon.com and authenticate with your Amazon credentials.
- Click on “Apps & Services”, then “Login with Amazon”
- Click on “Create a New Security Profile”
Figure 1 : Access Login With Amazon.
Fill in all three required fields to create your security profile and click “Save”. For the purpose of this post, the privacy URL points to Amazon’s. Make sure to replace the link with a link to your own Data Privacy policy.
Figure 2 : Create Security Profile
Before you complete this step, be sure to click on the link named “Show Client ID and Client Secret” (see Figure 3) and copy revealed values to a text editor so they're easily available. You’ll need these values later in a future step.
Figure 3 : Collect Client ID and Client Secret
Step 2: Initialize Creation of Smart Home Skill
In this step, you will start the process of creating an Alexa skill.
- Connect to https://developer.amazon.com and authenticate with your Amazon credentials.
- Click on “Alexa”, then click the “Get Started” button in the “Alexa Skills Kit” box.
Figure 4: Alexa Skills Kit
- Click on “Add a New Skill” button in the upper right of screen.
- Select “Smart Home Skill API”, enter a name, and click the “Save” button.
Figure 5: Create a New Alexa Skill
- Now click on the “Skill Information” link to go back to previous screen.
Figure 6: Interaction Model
- The Skill Information page now shows your skill’s Application ID (see Figure 7). Copy the ID and save it to a text file as it will be used in the next step.
Figure 7 : Skill Application ID
Step 3: Create an AWS Lambda Function
Skills developed with the Smart Home Skill API must be hosted in an AWS Lambda function. Here is how to create it.
- Connect to https://aws.amazon.com and authenticate with your Amazon credentials. If you have not created an AWS account, do so now.
Once in the AWS Console, select “Services,” then “All AWS Services,” and choose “Lambda.”
Figure 8: AWS Services
- Click on the “Create a Lambda function” button.
- In the screen that appears under “Select Blueprint”, choose a runtime of your choice (Node.js 4.3 is selected in Figure 9) and type “smart” into the filter. Select “alexa-smart-home-skill-adapter.”
Figure 9 : Select blueprint
A new screen appears prompting for an Application Id. Enter the value you collected from step two (see Figure 7), and click the “Next” button.
Figure 10: Lambda Application Id
- Under “Configure function”, provide a name, description, and confirm runtime is the same as the one you chose previously (see Figure 9)
Figure 11 : Configure function
- Under “Lambda function code”, clear all the existing code and replace with two forward slashes // which represents a single line comment in JavaScript.
Figure 12 : Lambda function code
- Under “Lambda function handler and role”, for “Existing role” choose “lambda_basic_execution” and leave all other values as is. Click the “Next” button.
Figure 13 : Lambda function handler and role
- On the review screen, find the “Create function” button at the bottom of the screen and click it. You should receive confirmation the Lambda function has been successfully created.
Figure 14 : Lambda ARN
- Copy the ARN (see Figure 14) value to a text file for use in the next step. No further action will be needed in the AWS console. In a future blog post, you will learn how to write code in the skill adapter.
Step 4: Configure Smart Home Skill
The skill started in the second step of this article will now be configured to support account linking.
- Return to https://developer.amazon.com and authenticate with your Amazon credentials.
- Click on “Alexa”, then click on the “Get Started” button in the Alexa Skills Kit box.
- In the developer portal, find the skill you created in step 2, and click the “Edit” button.
Figure 15: Edit Skill
- On your skill screen, click on the “Configuration” link
Figure 16 : Configuration
- Fill in values for the configuration screen (see Figure 17). An explanation of the values is provided in Table 1. Copy the value of the “Redirect URL” to a text file as it will be needed shortly. When finished, click the “Next” button.
Figure 17: Configure Account Linking
Table 1 : Skill configuration values
| Key |
Value |
| Endpoint |
ARN value from skill adapter hosted in AWS Lambda function (See Figure 14) |
| Authorization URL* |
(note that this is different from the authorization URL for custom skills as shown in Sebastien’s LWA blog post)
|
| Client ID* |
The client ID value received from LWA during the first step. (See Figure 3) |
| Domain List |
A list of up to 15 domains the authorization URL will fetch content from. No additional domain names were needed in this example. |
| Scope* |
LWA supports several scopes. for this example, let’s use “profile”. This will allow your code to retrieve a unique Amazon userid, email address, and full name for the user. |
| Authorization Grant Type |
“Auth Code Grant” is required for smart home skills. |
| Access Token URI* |
This is the URI the Alexa Service needs to use to exchange an authorization code for a token and to refresh expired tokens. This is the same value for all Login with Amazon applications : https://api.amazon.com/auth/o2/token |
| Client Secret* |
The client secret value received from LWA during the first step. (See Figure 3) |
| Client Authentication Scheme * |
HTTP Basic (recommended) |
* Values provided are specific to LWA. If using another OAuth 2.0 provider, refer to its support documentation for how to obtain these values.
- On the test screen of your skill, confirm your skill is enabled for “Show this skill in the Alexa App.”
Figure 18 : Show this skill in the Alexa App.
You are finished with this step. You may optionally provide publishing information if you click the “Next” button, but it is not required in the context of this article.
Step 5: Finalize Account Linking and Confirm
This final step will take you full circle to the first step. A small but significant value needs to be added to the LWA profile for account linking to function correctly. Here is what to do.
- Connect to https://developer.amazon.com and authenticate with your Amazon credentials.
- Click on “Apps & Services”, then “Login with Amazon”
- Under “Login with Amazon Configurations”, find the profile created in the first step and click the settings icon on the right. Select “Web Settings” option.
Figure 19 : Login with Amazon Configurations
- In the profile management page, click the “Edit” button.
- In the “Allowed Return URLs” field, provide the Redirect URL value collected in Step 4 (see Figure 17). When finished, click the “Save” button.
Figure 20 : Allowed Return URLs
Your LWA profile is complete. It is now time to confirm account linking was successfully configured by enabling the smart home skill in the Alexa companion app. Here is what to do.
- Open your Alexa companion app, and select “Skills” from main menu.
- In the skills screen, locate the “Your Skills” link at the top and select it.
Figure 21 : Your Skills
- Find the smart home skill you created and select it
Figure 22 : Select smart skill in development
- On the skill information page select “Enable Skill” button
Figure 23 : Enable Skill
- Sign in to your skill using your Amazon account
Figure 24 : Sign in
- You will receive confirmation that Alexa is linked with your skill. If prompted to discover devices, select “Cancel” button.
Figure 25 : Alexa has been successfully linked
Congratulations, you have met the prerequisites for creating a skill using the Smart Home Skill API.
What next?
Well if you recall, the code file in skill adapter was left blank. This was done to prove that enabling account linking with the Smart Home Skill API does not require code. However, accessing account values, enabling device discovery, and controlling devices all require code. These topics will be covered in upcoming articles, so stay tuned.
