感谢您的访问。此页面目前仅提供英语版本。我们正在开发中文版本。谢谢您的理解。

Step 1: Create Your Video Skill and Lambda Function (VSK FTV)

In this step, you will set up a video skill through the Alexa developer console and also create a basic Lambda function on AWS to process communication from the video skill.

Sample App Instructions

Even if you're working with the sample Fire TV app, you must still complete all the tasks described in this topic.

Video Skill and Lambda Overview

With Fire TV apps, Alexa listens for utterances from users and then converts the utterances into directives. A directive is a set of data and instructions, expressed in JSON, sent from Alexa to your Lambda function in the cloud.

For example, when a user says "Play Bosch," Alexa converts this into a search directive that has a specific JSON structure. Other types of directives include play directives, channel change directives, and more. Alexa does the work of mapping the user's utterances into the formal directives that can be processed programmatically.

The Video Skill API then delivers these directives to your Lambda code on AWS. Lambda is an AWS service that runs code in the cloud without requiring you to have a server to host the code. Your Lambda code can process the directives from the video skill. Your Lambda then sends actions to your app using Amazon Device Messaging (ADM).

Step 1.1: Begin Creating a Video Skill

In this step, you'll begin creating a video skill so that you can get the skill's Application ID. This Application ID will be used when you create your Lambda function.

To begin creating your video skill:

  1. Go to https://developer.amazon.com.
  2. In the upper-right corner, click Developer Console. If you're not signed in, you'll be prompted to sign in.
  3. In the top navigation, click Alexa and select Alexa Skills Kit.
  4. Click Create Skill.
  5. Under the Skill name field, type a simple name for your skill (usually the name of your app, such as Streamz).

  6. Under "Choose a model to add to your skill," select the Video square.

    Creating a video skill in the Alexa Developer Console
    Creating a video skill in the Alexa Developer Console
  7. Click Create skill in the upper-right corner.

  8. Click Copy to clipboard next to Your Skill ID (highlighted in the screenshot below).

    Copying the Video Skill ID
    Video Skill ID

    Store this information in a simple text file on your computer, as you'll be gathering other information here as you proceed through this tutorial. You will need this Skill ID value when you create the Lambda function for your video skill.

    Notice that the Video Skill Configuration requires you to configure a default endpoint, specifically an ARN (Amazon Resource Name) for a Lambda function.

    ARN required to configure video skill
    ARN required to configure video skill

    Before you continue configuring your video skill, you need to pause here to get an ARN. To do so, you will need to create an IAM role and Lambda function by following the sections below. You can open a new tab to avoid losing your place in the video skill (though your session will likely time out).

Step 1.2: Create an IAM Role for your Lambda

This task is preparatory to creating your Lambda function (which your video skill will interact with). You need to define permissions that specify which applications can invoke your Lambda function. Here you'll create an IAM role that allows Lambda functions to call AWS services, such as Cloudwatch, on your behalf. To create the IAM role:

  1. Sign in to the AWS Managment Console.
  2. In the upper-right, select the AWS region based on the following table.

    Selecting an AWS region
    Selecting an AWS region

    Selecting a region close to your customers will ensure that the latency between customer utterances and Lambda invocations is minimal. Also, the video skill won't work if you select the wrong AWS region.

    Skill Language Customer Region AWS 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)
  3. Click Services and go to IAM (use the Search box).
  4. Select Roles from left navigation, and then click Create role.
  5. Under AWS service (selected by default), click Lambda, and then click Next: Permissions at the bottom.
  6. Search for AWSLambdaBasicExecutionRole and select the check box next to it; then click Next: Tags.
  7. Skip the "Add tags (optional)" configuration and click Next: Review.
  8. Give your role a name (for example, "video_skill_streamz") and description as you like, and click Create role.

    Creating an IAM role that can interact with your Lambda
    Creating an IAM role that can interact with your Lambda

    Make a note of your IAM role name (especially if you have multiple IAM roles in AWS) so that you can easily remember it for the next step.

Step 1.3: Create the Lambda Function for Your Video Skill

Now you'll create the Lambda function that your video skill will use. Creating the function will give you an Amazon Resource Name (ARN), which is required to configure your video skill. To create the Lambda function for your video skill:

  1. In the AWS Management Console, click Services and go to Lambda (use the Search box).
  2. Click Create function.
  3. Leave Author from scratch selected as is, and then complete the following:
    • Function name: A unique name for your Lambda function (for example, firetv_app_lambda.
    • Runtime: Node.js 8.10 (Node JS is what the sample Lambda code is written in for this integration. Later, you can explore using other languages for your Lambda, such as Python, Ruby, .NET, Java, etc.).
    • Permissions
      Creating a basic Lambda function in AWS
      Creating a basic Lambda function in AWS
  4. Click Create function.

    Your Lambda function is created. Note that your Lambda function will not receive directives from Alexa unless your add a Smart Home trigger that tells the Lambda where it should get the message from. This is what the Smart Home API does — connect your devices to Lambda computing in the cloud. However, in order to configure the Alexa Smart Home trigger, you need the Application ID for your video skill.

  5. In the Designer section, click + Add trigger.
  6. In the Trigger configuration, select Alexa Smart Home and then enter your video skill ID (created in section 1.1) in the Application ID field. Then click Add.

    Configuring Lambda with your Video Skill ID
    Configuring Lambda with your Video Skill ID

    After you click Add, you receive a success notification that says, "The trigger [123456…] was successfully added to function [Lambda function name]. The function is now receiving events from the trigger."

    In this case, the trigger is your video skill. Your Lambda function will now receive events from your video skill.

  7. The ARN for your Lambda function appears in the upper-right corner of the page, as shown in the following screenshot. Copy your Lambda's ARN and make a note of it, as you will need it in the next section (Step 1.4: Finish Setting Up Your Video Skill) to configure your video skill.

    Location of the ARN for your Lambda function
    Location of the ARN for your Lambda function
  8. Click your Lambda function's name (the box with Lambda icon ) in the center of the page. This will expand a code editor in the pane below.
  9. To facilitate the initial setup, we’ve included some basic Lambda code. This code provides a starting point for implementing a video skill. The code will respond to the directives from Alexa and communicate with your Fire TV app. Do the following:

    1. Click the Copy button below to copy the code to your clipboard.
    2. Paste all of the code from that file into the function code editor exactly as is, replacing the existing code in the editor's index.js file.
    3. Click Save in the upper-right corner.

Copied to clipboard.

/**
* Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Amazon Software License (the "License"). You may not use this file except in # compliance with the License.
* A copy of the License is located at http://aws.amazon.com/asl/
*
* or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS
* OF ANY KIND, express or implied. See the License for the specific # language governing permissions and limitations under the License.
**/

// This file includes sample lambda code for a Video Skills API integration on Fire TV,
// including responses for Discovery, SearchAndPlay, FastForward, Channel Change, and other
// directive types. Partners should use this code as a starting point, but then add their
// own logic. Partners should test and validate any code before using it in production.
// Amazon's recommended approach is to take directives received by the lambda and send
// them directly to the app via ADM. Any further processing can occur within the app.
// NOTE: Responses back to Alexa should NOT be modified, only code to process/send directives.
// NOTE: You should send directives from the lambda to your app, but you should NOT try
// to send messages from your app back to the lambda. Success responses from the lambda
// are only meant to indicate that the message was received by the lambda, not the app.

var AWS = require('aws-sdk');

exports.handler = (event, context, callback) => {
    console.log("Lambda was invoked by Alexa");
    console.log("Event: " + JSON.stringify(event, null, 2));
    console.log("Context: " + context);
    let directive = event.directive;
    if (directive)
    {
        console.log("Directive received from Alexa: " + directive);
        if (directive.header.name == "Discover")
        {
            console.log(directive.header.name, " directive received from Alexa");
            let resp = {
               event: {
                   header : {
                       messageId : directive.header.messageId,
                       name : "Discover.Response",
                       namespace: "Alexa.Discovery",
                       payloadVersion: "3"
                   },
                   "payload": {
                       "endpoints": [
                           {
                               "capabilities": [
                                   {
                                       "interface": "Alexa.RemoteVideoPlayer",
                                       "type": "AlexaInterface",
                                       "version": "1.0"
                                   },
                                   {
                                       "interface": "Alexa.PlaybackController",
                                       "type": "AlexaInterface",
                                       "version": "1.0"
                                   },
                                   {
                                       "interface": "Alexa.SeekController",
                                       "type": "AlexaInterface",
                                       "version": "1.0"
                                   },
                                   {
                                       "interface": "Alexa.ChannelController",
                                       "type": "AlexaInterface",
                                       "version": "1.0"
                                   }
                               ],
                               "endpointId": "VSKTV",
                               "description": "VSKTV is the default device used for video skills developed for Fire TV integrations",
                               "friendlyName": "VSKTV",
                               "manufacturerName": "Amazon"
                           }
                       ]
                    }
               }
            };
            console.log("Sending ", directive.header.name, " response back to Alexa: ", JSON.stringify(resp));
            callback(null, resp);
        }
        else if (  directive.header.name == "SearchAndPlay"
				|| directive.header.name == "SearchAndDisplayResults"
				|| directive.header.name == "Play"
				|| directive.header.name == "Resume"
				|| directive.header.name == "Pause"
				|| directive.header.name == "Next"
				|| directive.header.name == "Previous"
				|| directive.header.name == "Rewind"
				|| directive.header.name == "FastForward")
        {
            console.log(directive.header.name, " directive received from Alexa");

			// Partner-specific logic to handle the the directives goes here
			// Code for sending directive from the lambda to the app goes here

            // Below, we send a "success" response back to Alexa, indicating the directive was received by the lambda
            let resp = {
                event: {
                    "header" : {
                        "messageId": "not-required",
                        "correlationToken": "not-required",
                        "name": "Response",
                        "namespace": "Alexa",
                        "payloadVersion": "3"
                    },
                    "endpoint": {
                        "scope": {
                            "type": "DirectedUserId",
                            "directedUserId": "not-required"
                        },
                        "endpointId": "not-required"
                    },
                    "payload": { }
                }
            };
            console.log("Sending ", directive.header.name, " response back to Alexa: ", JSON.stringify(resp));
            callback(null, resp);
        }
        else if (directive.header.name == "AdjustSeekPosition")
        {
            console.log(directive.header.name, " directive received from Alexa");

			// Partner-specific logic to handle the AdjustSeekPosition directive goes here
			// Code for sending this directive from the lambda to the app goes here

            // Below, we send a "success" response back to Alexa, indicating the directive was received by the lambda
            let resp = {
                event: {
                    "header" : {
                        "messageId": "not-required",
                        "correlationToken": "not-required",
                        "name": "StateReport",
                        "namespace": "Alexa.SeekController",
                        "payloadVersion": "3"
                    },
                    "endpoint": {
                        "scope": {
                            "type": "DirectedUserId",
                            "directedUserId": "not-required"
                        },
                        "endpointId": "not-required"
                    },
                    "payload": {
                      "properties": [{
                        "name": "positionMilliseconds",
                        "value": 0
                      }]
                    }
                }
            };
            console.log("Sending ", directive.header.name, " response back to Alexa: ", JSON.stringify(resp));
            callback(null, resp);
        }
		else if (directive.header.name == "ChangeChannel")
        {
            console.log(directive.header.name, " directive received from Alexa");

			// Partner-specific logic to handle the ChangeChannel directive goes here
			// Code for sending this directive from the lambda to the app goes here

            // Below, we send a "success" response back to Alexa, indicating the directive was received by the lambda
            let resp = {
                context: {
                    "properties": [
                    {
                        "namespace": "Alexa.ChannelController",
                        "name": "channel",
                        "value": {
                            "number": "1234",
                            "callSign": "not-required",
                            "affiliateCallSign": "not-required"
                        },
                        "timeOfSample": "2017-02-03T16:20:50.52Z",
                        "uncertaintyInMilliseconds": 0
                    }
                    ]
                },
                event: {
                    "header" : {
                        "messageId": "not-required",
                        "correlationToken": "not-required",
                        "name": "Response",
                        "namespace": "Alexa",
                        "payloadVersion": "3"
                    },
                    "endpoint": {
                        "endpointId": "not-required"
                    },
                    "payload": { }
                }
            };
            console.log("Sending ", directive.header.name, " response back to Alexa: ", JSON.stringify(resp));
            callback(null, resp);
        }
        else if (directive.header.name == "AcceptGrant")
        {
            console.log(directive.header.name, " directive received from Alexa");
            let resp = {
                "event": {
                    "header": {
                        "messageId": "abc-123-def-456",
                        "namespace": "Alexa.Authorization",
                        "name": "AcceptGrant.Response",
                        "payloadVersion": "3"
                        },
                "payload": {}
              }
            };
            console.log("Sending ", directive.header.name, " response back to Alexa: ", JSON.stringify(resp));
            callback(null, resp);

        }
        else
        {
			console.log("Directive is not supported. Ignoring it.");
			callback(null, 'Directive is not supported. Ignoring it.');
        }
    }
    else
    {
		console.log( 'Directive is null. Ignoring it.');
        callback(null, 'Directive is null. Ignoring it.');
    }
};

The following screenshot shows the code editor where you insert the code.

Lambda function code editor
Lambda function code editor

More explanation and instruction regarding the Lambda code and logic will be given later (in Step 6: Create and Deploy Lambda Package, when you customize this Lambda function). But briefly, the Lambda function will receive directives sent from Alexa. Remember that Alexa listens for customer phrases (e.g., Play Interstellar) and packages up the request as a directive (a JSON object).

Your Lambda receives this directive from Alexa and takes some action. First, your Lambda determines the request type by identifying the namespace and name values in the directive's message header. For example, the namespace specifies whether the request is a Discovery or ChannelControl directive. Depending on this namespace, either the handleDiscovery or handleChannelControl function is called.

The Lambda function in this sample code does not initiate any actions to perform. In a later step (Step 6: Create and Deploy Lambda Package), you will customize this code more, creating logic for actions to perform and providing basic responses about the messages received.

When you customize the Lambda code in more detail, you will need to handle every type of request a user would make to your skill and provide the correct response in your app through Amazon Device Messaging (ADM). Later in the tutorial, you will test your video skill for the way it handles various directives.

For now, you're finished setting up the basic Lambda code. The Lambda code here is generic and will return information about any video content listed in Gracenote . In other words, you'll get information about every instance of the media across all of the app catalogs.

Later, you'll return to this Lambda code and customize it with your app's catalog; when you do, the responses will be scoped to your app's catalog only. Additionally, the later sections will provide more detail about the Lambda code's logic.

Step 1.4: Finish Setting Up Your Video Skill

Return to the video skill you started setting up in Step 1.1: Begin Creating a Video Skill and complete the video skill setup.

To finish setting up your video skill:

  1. Return to your video skill in the Alexa developer console.
  2. In the list of Alexa Skills, click the video skill you started earlier. (If you left this screen open, make sure you're still signed in by refreshing the page.)
  3. Paste the Lambda's ARN into the Default endpoint box. (You copied this ARN in Step 1.3: Create the Lambda Function for Your Video Skill.)
  4. In the "Pick a geographical region … " section, you can select different Lambda ARNs based on different regions to the reduce the latency between Alexa and your Lambda. Based the your AWS region you selected earlier, paste your ARN into one of these regions.

    Configuring your video skill with your Lambda ARN
    Configuring your video skill with your Lambda ARN
  5. In the Country Specific Configuration selection, select a country for your skill. By default, a country should already be selected (e.g., United States). If your video skill will be available in more than one country, click Add Country and add the additional countries.

    Below the country you will see a sub-section titled "A. [Country name] Configuration." This lists the Catalog details for the country. If you added more countries, you see additional Catalog details for each country. For example, if you added both United States and Canada for your video skill, you see two Catalog subsections as follows:

    Catalog subsections corresponding to countries
    Catalog subsections corresponding to countries
  6. In the Catalog Name field, enter the name of your catalog (for each country).

    As noted in the introduction, Catalog integration is required for video skills. When users request a media title, Amazon will look within your catalog for title matches and send you the corresponding identifiers. For more details about catalog integration, including the CDF format, see the Catalog documentation.

    Sample catalog for testing video skills with a Fire TV app

    For the simple setup of seeing a test video skill in action on a Fire TV device, you can use the following catalog names: hawaii_us (for US skills). Or hawaii_ca (Canada), hawaii_de (Germany), hawaii_es (Spain), hawaii_gb (Great Britain), hawaii_in (India), hawaii_it (Italy), hawaii_jp (Japan). This catalog, used for testing, just contains a few Creative Commons videos (e.g., Big Buck Bunny, Elephants Dream, Cosmos Laundromat, Caminandes: Llamigos, and Tears of Steel (as noted in this feed).
  7. Ignore the MSO ID, as this field is not used for video skills on Fire TV apps. (MSO stands for multiple-system operator and is used for live TV integration of video skills into set-top boxes.)
  8. In the Language Specific Configuration section, select the language for your video skill. Languages corresponding to the countries you selected earlier will automatically be added, but you can add additional languages as desired by clicking Add Language. Each additional language you enter will create a corresponding subsection with Skill Invocation details.

    For example, suppose your video skill is available in both United States and Canada. As a result, two languages are selected by default: en-US and en-CA. As a result, you see two subsections to configure the skill invocation for each of these languages: "A. English (United States): en-US Configuration" and "B. English (Canada): en-CA Configuration," as shown in the following screenshot:

    Language-specific configuration by country
    Language-specific configuration by country

    These subsections allow you to customize the video skill invocation names and image assets for each language. For example, suppose your video skill name differs between the two locations, or has a different logo image, you could customize the invocation and display appropriately through these subsections.

  9. In the Alternate Skill Invocation boxes, enter additional ways to invoke your skill. By default, your video skill can be invoked by the name you gave it when you created the skill (in section Step 1.1: Begin Creating a Video Skill). But you can create alternate names here as well.

    For example, suppose your skill was named XYZ. Users could say, "Play the movie Big Buck Bunny on XYZ" to invoke your video skill. (This utterance explicitly targets your skill.) If you added an alternate skill invocation of "ACME," then users could say "Play the movie Big Buck Bunny on ACME" and Alexa would target your video skill through this invocation as well.

  10. Scroll back up to the top and click Save.
  11. Click Account Linking in the left navigation.
  12. Configure the fields as described in the following table.

    Entering sample OAuth values for video skills

    As you are creating a video skill, you can enter some test OAuth values here for now. Later in the tutorial, you will go back and add the correct OAuth configuration needed for account linking. Reach out to your Amazon contact for some test OAuth values you can enter.
    Account Linking Fields
    Field Description
    Authorization URI If you haven't set up OAuth yet, reach out to your Amazon contact for a test value you can enter here.
    Access Token URI If you haven't set up OAuth yet, reach out to your Amazon contact for a test value you can enter here.
    Client ID Enter alexa-skill
    Client Secret If you haven't set up OAuth yet, reach out to your Amazon contact for a test value you can enter here.
    Client Authentication Scheme Leave at the default: HTTP Basic (Recommended)
    Scope Click +scope and add any simple one-word name (for example, appscope).
    Domain List Skip this field.
    Default Access Token Expiration Time Leave blank.
    Redirect URLs Skip this field.
  13. Click Save.
  14. Click the Distribution tab from the top navigation and ensure that all fields are filled in, including all icons. You can modify these fields later if needed (since you don't need to officially publish your skill to test it), but at least put some stub values in each field for now. The following table describes each field.

    The following table describes each of the fields:

    Distribution Fields
    Field Description
    Public Name The name of the skill shown to customers in the Alexa app. Use your app's name (for example, "ACME").
    One Sentence Description A quick at-a-glance sentence that describes the skill or what customers can do with it (for example, "This skill allows you to use your voice to interact with ACME."). This text appears as the first line in your Alexa skill's description.
    Detailed Description Describe how to use the skill (for example, "Search for your favorite shows by name, control playback with common commands, change channels, and more.").
    What's new Release notes for your skill. (For example, "First release of skill.")
    Example Phrases Sample utterances users can say in your app. Put each utterance on a new line. The sample phrases should correspond with the video skill functionality you implemented. For example:
    • "Alexa, search for [TV show] on ACME."
    • "Alexa, play [movie] on ACME."
    • "Alexa, tune to ACME."
    • "Alexa, rewind 30 seconds."
    • Alexa, show episodes of [TV show] on ACME.
    Small Skill Icon A 108 x 108px icon (PNG or JPG) to represent your skill in the Alexa app. The image must accommodate a circular design. If you don't have an image, either use the stock image below or create one using the Alexa Skill Icon Builder. (Right-click the image below and save it to your computer.)
    108 x 108px icon
    Large Skill Icon A 512 x 512px icon (PNG or JPG) that provides a larger version of the same icon. This icon appears in the Alexa Skills section of Amazon.com. If you don't have an image, either use the stock image below or create one using the Alexa Skill Icon Builder. (Right-click the image below and save it to your computer.)
    512 x 512px icon
    Category Select Video
    Keywords Simple search words that describe this skill. For example, you might list variations on your app's name and the most popular shows in your app. This helps customers find the skill quickly and easily. Use spaces or commas in between each search term.
    Privacy Policy URL Link to the privacy policy that applies to this skill. (If you don't have one, link to your website for now.)
    Terms of Use URL Link to the terms of use document for this skill. (If you don't have one, link to your website for now.)
  15. When you finish with the required fields, click Save and continue. You'll be presented with the next screen in the left navigation: Privacy & Compliance.
  16. Complete the Privacy & Compliance fields. Note that you must include some content in Testing Instructions.

  17. When you're finished on this screen, click Save and continue. You'll be presented with the next screen in the left navigation: Availability.

  18. Complete the Availability fields. Make sure Public is selected and select the appropriate locations (select the same regional availability for your video skill as your app's availability). Then click Save and continue.
  19. You're taken to the Certification tab, specifically to to the "Validation" side tab. Assuming you completed all the required fields, you should see "Zero errors found."

    Video skill configured and ready for testing
    Video skill configured and ready for testing

    There's no need to move through the Functional test and Submission pages. Also, you don't need to submit your video skill at this time. You can test your skill while you are still developing it.

Next Steps

Continue on to the next step: Step 2: Enable your Video Skill on an Echo Device and Test.