Vielen Dank für Ihren Besuch. Diese Seite ist momentan nur auf Englisch verfügbar. Wir arbeiten an der deutschen Version. Vielen Dank für Ihr Verständnis.

Steps to Build a Smart Home Skill

This topic provides the steps for creating a smart home skill that responds synchronously to directives. The steps will walk you through skill creation in the developer console, creating an AWS Lambda function, configuring and testing your skill, and submitting it for certification.

Register as an Amazon Developer and Create the Skill

To configure a new smart home skill, you need an account on the Amazon Developer Console. If you don’t already have an account, go to https://developer.amazon.com/alexa/console/ask and create an account. Registering is free. Once you’ve registered:

  1. Open the Amazon Developer Console in a browser.
  2. Click the Create Skill button.
  3. Enter the Skill name. Note that your skill's name must not indicate that it's functionality is limited. For example, you should not use "basic", "reduced" or "simple" in the title of your skill. The skill will default to English (US). Change the Default language using the drop-down, if you are targeting a different region/language. See Build Smart Home Skills in Multiple Languages to see the device categories that are supported for each language.
  4. Under Choose a model to add to your skill page, select Smart Home, which is a pre-built model, and click Create skill.
  5. Under Payload Version, select v3.
  6. Click Save and copy Your Skill ID to the clipboard. The ID will be in a format similar to the following: amzn1.ask.skill.1a2b55555-c325-1234-d56e-1f234d5e6a78

For more information on how to use the developer console, see Manage Skills in the Developer Console.

Next, you will create a Lambda function so that you can configure the Smart Home service endpoint.

Add a Lambda Function

You will need an AWS account and some basic knowledge of AWS. The code for your smart home skill is hosted as a Lambda function on AWS. AWS Lambda is a service that lets you run code in the cloud without managing servers. Alexa sends your skill requests and your code inspects the request, takes any necessary actions such as communicating with the device cloud for that customer, and then sends back a response.

To get started, sign in to your AWS Account,.

Create an IAM Role for Lambda

If you haven't worked with Lambda before, you will need to create an Identity and Access Management (IAM) role that enables basic execution. To create an IAM role. Navigate to the IAM console. If you already have a role that enables Lambda basic execution, skip to the next section.

  1. Choose Roles and click Create a new role.
  2. Select AWS Lambda under AWS Service Role.
  3. Type "basic" in the filter box and choose the AWSLambdaBasicExecutionRole, and click Next Step.
  4. Enter a name that identifies this role and click Create role.

Create a Lambda function and add code

  1. On the AWS Console, under Compute, select Lambda.
  2. Make sure you’ve selected:
    • N.Virginia for English (US) or English (CA) skills
    • EU (Ireland) region for English (UK), English (IN), German or French (FR) skills
    • US West (Oregon) for Japanese and English (AU) skills.

    The region is displayed in the upper right corner. Providing your Lambda function in the correct region prevents latency issues.

  3. Click Create a Lambda function.
  4. Select Author from scratch, and enter the following information:

    • Name: Provide a name for your Lambda function. This name is appears in the AWS console and is also returned by the AWS command line interface (CLI) ListFunctions API. It should be unique across your Lambda functions.
    • Runtime: To use the sample code provided in this topic, choose Node.js 6.10 or alternatively, select the runtime for the code you plan to write. Supported languages are: Node.js, Java, Python, C#, or Go.
    • For Role, select a role you previously created, or a role with Lambda basic execution policy attached.
  5. Click Create Function. Your function should be created and you will move to Configuration.
  6. In the Configuration designer, under Add triggers select the Alexa Smart Home trigger.
  7. In the Configure triggers section, add the Skill ID from the developer console in the box specified. 
  8. Leave Enable trigger checked. This enables the Amazon Alexa service to call your Lambda function. If you don't enable it when you create, you will not be able to enable it in the console later.
  9. Click Add and then click Save.
  10. At the top of the page, select the Lambda function to display the function code. Following is an example of the Lambda function.
  11. In the Function code section make sure Edit code inline is selected. Leave the Runtime and Handler set to their defaults.
  12. Paste in the following code, completely replacing the code in index.js.
exports.handler = function (request, context) {
    if (request.directive.header.namespace === 'Alexa.Discovery' && request.directive.header.name === 'Discover') {
        log("DEBUG:", "Discover request",  JSON.stringify(request));
        handleDiscovery(request, context, "");
    }
    else if (request.directive.header.namespace === 'Alexa.PowerController') {
        if (request.directive.header.name === 'TurnOn' || request.directive.header.name === 'TurnOff') {
            log("DEBUG:", "TurnOn or TurnOff Request", JSON.stringify(request));
            handlePowerControl(request, context);
        }
    }

    function handleDiscovery(request, context) {
        var payload = {
            "endpoints":
            [
                {
                    "endpointId": "demo_id",
                    "manufacturerName": "Smart Device Company",
                    "friendlyName": "Bedroom Outlet",
                    "description": "Smart Device Switch",
                    "displayCategories": ["SWITCH"],
                    "cookie": {
                        "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
                        "key2": "There can be multiple entries",
                        "key3": "but they should only be used for reference purposes.",
                        "key4": "This is not a suitable place to maintain current endpoint state."
                    },
                    "capabilities":
                    [
                        {
                          "type": "AlexaInterface",
                          "interface": "Alexa",
                          "version": "3"
                        },
                        {
                            "interface": "Alexa.PowerController",
                            "version": "3",
                            "type": "AlexaInterface",
                            "properties": {
                                "supported": [{
                                    "name": "powerState"
                                }],
                                 "retrievable": true
                            }
                        }
                    ]
                }
            ]
        };
        var header = request.directive.header;
        header.name = "Discover.Response";
        log("DEBUG", "Discovery Response: ", JSON.stringify({ header: header, payload: payload }));
        context.succeed({ event: { header: header, payload: payload } });
    }

    function log(message, message1, message2) {
        console.log(message + message1 + message2);
    }

    function handlePowerControl(request, context) {
        // get device ID passed in during discovery
        var requestMethod = request.directive.header.name;
        var responseHeader = request.directive.header;
        responseHeader.namespace = "Alexa";
        responseHeader.name = "Response";
        responseHeader.messageId = responseHeader.messageId + "-R";
        // get user token pass in request
        var requestToken = request.directive.endpoint.scope.token;
        var powerResult;

        if (requestMethod === "TurnOn") {

            // Make the call to your device cloud for control
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "ON";
        }
       else if (requestMethod === "TurnOff") {
            // Make the call to your device cloud for control and check for success
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "OFF";
        }
        var contextResult = {
            "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": powerResult,
                "timeOfSample": "2017-09-03T16:20:50.52Z", //retrieve from result.
                "uncertaintyInMilliseconds": 50
            }]
        };
        var response = {
            context: contextResult,
            event: {
                header: responseHeader,
                endpoint: {
                    scope: {
                        type: "BearerToken",
                        token: requestToken
                    },
                    endpointId: "demo_id"
                },
                payload: {}
            }
        };
        log("DEBUG", "Alexa.PowerController ", JSON.stringify(response));
        context.succeed(response);
    }
};

Finish configuring and test the Lambda function

  1. Click Save.
  2. If you want to perform a quick test of the Discovery request in the Lambda code editor, you can click on Test. The Configure test event page appears.
  3. Leave Create new test event selected. For Event template, leave the default Hello World. In the Event name, enter discovery and replace the entire contents in the editor with the following code.
{
    "directive": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover",
            "payloadVersion": "3",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            }
        }
    }
}
  • Click Create, and then Test. If successful, the Execution Result should be similar to the following:
{
  "event": {
    "header": {
      "correlationToken": "12345692749237492",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "name": "Discover.Response",
      "namespace": "Alexa.Discovery",
      "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "demo_id",
          "manufacturerName": "Smart Device Company",
          "friendlyName": "Bedroom Outlet",
          "description": "Smart Device Switch",
          "displayCategories": ["SWITCH"],
          "cookie": {
            "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
            "key2": "There can be multiple entries",
            "key3": "but they should only be used for reference purposes.",
            "key4": "This is not a suitable place to maintain current endpoint state."
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "interface": "Alexa.PowerController",
              "version": "3",
              "type": "AlexaInterface",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

Configure the Smart Home Service Endpoint

You must provide the ARN for your Lambda function in the skill configuration in the developer console.

  1. Navigate back to your skill in the Developer Console.
  2. Under 2. Smart Home service endpoint, in the Default endpoint box, provide the ARN number from the Lambda function you created and click Save. If you are creating multiple language versions of your skill, you must provide geographic-specific endpoints. The following table lists mapping between the language you select for your skill, the regional endpoint and regions for your Lambda function.
Skill language Endpoint Region Lambda Function Region
English (US), English (CA) North America US East (N. Virginia)
English (UK), French (FR), German, Italian, Spanish (ES) Europe, India EU (Ireland)
English (IN) Europe, India EU (Ireland)
Japanese, English (AU) Far East US West (Oregon)
  • If your skill only supports one language/region, provide the same ARN for the default ARN and the selected regional ARN.
  • If your skill supports multiple languages/regions, you must provide ARNs for each region. Provide one of the regional ARNs for the default.

Provide Account Linking Information

In the Section 3. Account Linking, click Setup Account Linking This section requires account information from your OAuth 2.0 provider, which enables customers to associate their device cloud account with your smart home skill. You can use Login with Amazon or another OAuth provider for this section. You provide:

  • Authorization URI for your OAuth provider
  • Client ID for your OAuth provider
  • A Scope, if required by your OAuth provider
  • Access token URI for your OAuth provider
  • Client Secret associated with your Client ID

For more details and instructions about the required fields, see Configure Authorization Code Grant. For an overview of account linking in smart home skills, see:

Test Your Skill

When your implementation is complete, and you've tested your Lambda function, you can functionally test your smart home skill.

  1. Make sure you have a smart home trigger added and enabled. To check this, go to the Lambda console, select your smart home skill, and make sure you have an Alexa Smart Home trigger.
  2. Sign in to the Alexa app (available on Android, IOS or the web at https://alexa.amazon.com) with the same credentials as your developer account.
  3. Find your skill in the Alexa app. To do this, go to Skills, and tap Your Skills in the upper right corner of the All Skills page. Scroll to DEV SKILLS and find your skill.
  4. Click the ENABLE button to enable the skill, and you will be directed to account-link the skill to a device cloud account. If you are unable to complete account linking, make sure you are using valid credentials for the device cloud. Otherwise, it is likely there is an issue with account-linking information you provided in the developer console. For help with this, see Alexa: Debugging account linking in the developer forums. If you want to remove account linking later, you should disable your skill in the Skills tab.
  5. Close the window and tap the DISCOVER DEVICES button in the Alexa app.
  6. If the skill does not discover devices, check the logs for your Lambda function to see if it received a discover directive from Alexa, and use the logs to troubleshoot the issue. Common issues include incorrectly formatted event responses.
  7. If your skill successfully discovers devices, return to the Test page of the developer console. On the Test page, move the test slider to Yes and use the Alexa Simulator to give Alexa commands using the device names found in the discovery process and utterances your skill supports. Make sure and test the skill with valid utterances and invalid ones, meaning ask your skill to do things that should work, and things that should not work, and in a variety of conditions, such as with a target device powered off.
  8. When you are satisfied with your smart home skill’s performance, you can provide it for beta testing or submit it for certification.

Provide Launch Information

To provide your skill to customers for beta testing or submit your skill for certification, you must provide some information that is used to describe your skill in the Alexa app.

  • Select Distribution, and on the English (US) Store Preview page, specify:

    • Public Name.
    • One Sentence Description
    • Detailed Description
    • Example Phrases
    • Small Skill Icon
    • Large Skill Icon
    • Keywords
    • Privacy Policy URL
    • Terms of Use URL.

Use the tooltips provided on the page for assistance in completing these fields. For more detailed instructions about how to complete these fields, see the Smart Home Skill Publishing Guide.

  • Click Save and Continue

On the Privacy and Compliance page, answer the questions provided. For Testing Instructions, provide test account credentials. You should make sure your testing instructions and other publishing information follows the guidelines in our Publishing Guide.

  • Click Save and Continue
  • On the Availability page, check whether your skill is public, or for use by Alexa for Business Organizations.
  • Select the countries and regions you would like to distribute your skill
  • Click Save and Continue

Optionally Do Beta Testing

At this point, the Beta Test button should be enabled, and you can complete information to start a beta test. For more information, see Skills Beta Testing.

Submit Your Skill for Certification

If you have completed all of the fiends successfully, you should see a large green check mark and Your skill is ready for submission.

  • At the bottom of the page, click Submit for review.

Note that skill certification is different than Works with Alexa certification for devices. See Certify Your Device with Works with Alexa for more information.

Submit Changes to a Live Skill

Once your skill is live, any changes to the skill must be certified. For example, your skill must be recertified as part of changing the information you provided about your skill in the developer console or changing the AWS Lambda function. The certification review varies depending on the changes, and updating the Lambda function may trigger additional review.

When a skill status is changed to live, a new Development version is automatically created in the developer console and displays immediately below the live skill. This version has the same information as the original live version. You can use it to continue to work on your skill to improve it and add features.

When you submit your updated skill to the developer console, in the Testing Instructions field, add a change log that provides a detailed description of all changes.

To Update Your Lambda function

Do the following to update your AWS Lambda function:

  1. Create a new Lambda function with a new ARN, and copy your live Lambda function into the new Lambda function.

  2. Make your updates in the new Lambda function. Avoid updating the live Lambda function that supports your live skill, and avoid Lambda aliases or versioning because they do not work reliably once your skill is updated.

  3. In the development stage for your skill, update the Lambda ARN configuration to point to the new Lambda ARN.

After your skill is recertified and pushed live, your skill points to the new Lambda ARN. You can then deprecate the previous Lambda function or use the function for future development or updates.

Implement State Reporting

State reporting is recommended for all smart home skills because it provides the best customer experience. For more information, see Understand State Reporting in a Smart Home Skill. State reporting is required for smart home skills that target devices that are certified as Works With Alexa. For more details, see Works with Alexa Requirements for a Smart Home Skill.

Complete the following steps to implement state reporting: