Steps to Build a Video Skill for Living Room Entertainment Devices

When you create a new video skill, you enable Alexa to invoke your skill to fulfill a user request to control the video experience on a smart home video device. Video skills use the pre-built voice interaction model and Alexa defines the set of utterances for you. You can create an Alexa video skill for living room devices, such as game consoles, and smart TVs.

For an overview of video skills, see Understand Video Skills. If you want to create video skills for Fire TV, see Video Skills Kit for Fire TV. If you want to build video skills for Echo devices with a screen, see Video Skills Kit for Echo Show.

Complete the following steps to build a video skill.

Prerequisites

Before you develop a video skill, make sure that you have the following items:

  • An Amazon developer account. You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
  • An Amazon Web Services (AWS) account. The AWS account gives you access to resources as part of the free tier of services. You host your skill code on AWS Lambda.
  • A video device, such as set-top boxes, game consoles, and smart TVs, or video streaming service that connects to the device cloud. Your skill communicates with your device, or device cloud, by using communication channels supported by your device.
  • An Alexa-enabled device, such as an Amazon Echo. Make sure that you sign in to the Echo with the same credentials as your Alexa developer account.
  • The Amazon Alexa app on your mobile device. For instructions about how to download the Alexa app, see Download the Alexa app on the Amazon website. Make sure that you sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.
  • Knowledge of JSON and one of the supported programming languages for AWS Lambda skill code: Node.js, Java, Python, C#, Go, Ruby, or PowerShell.
  • An OAuth 2.0 provider for account linking. You can use the Amazon authorization server, called Login with Amazon (LWA), or you can choose your own OAuth 2.0 provider.
  • Appropriate Video Skill APIs for the directives to control your video device. For details about the supported locales and languages for Video Skill APIs, see List of Alexa Interfaces and Supported Languages.
  • Familiarity with the skill certification requirements for policy and security.

Steps to build a video skill

To build a video skill, complete the following steps:

  1. Create a video skill.
  2. Implement skill code.
  3. Configure account linking.
  4. Test your skill.
  5. Provide publishing information.
  6. Beta test your skill (optional)
  7. Submit your skill for certification

Step 1: Create a video skill

You create a video skill in the Alexa developer console. When prompted to choose a model to add to your skill, select the Video model.

You can choose English(US) as your default language and region, or you can create your skill in another language and region. Make sure to select the region where you plan to make your skill available. You can create your skill in other languages. For details, see Develop Smart Home Skills for Multiple Languages. Language support varies by interface. For more details, see List of Alexa Interfaces and Supported Languages.

After you create your skill, copy the skill ID to a convenient place, such as Notepad on Windows or TextEdit on Mac. You use the skill ID to connect your skill to your skill code hosted on Lambda.

Specify your catalog and lineup

Amazon gives users access to the public media catalogs, such as IMDB. If you support a private media catalog, you can submit your catalog to Amazon. In Country Specific Configuration specify the private catalog supported in each country that you plan to make your skill available. If your skill supports live TV, you specify your multiple system operator (MSO) ID.

Configure your skill invocation name

Users invoke your video skill by the skill name. For example, "Alexa, play Star Wars: Return of the Jedi on <skill name>." If you want to customize the invocation name, in Language Specific Configuration, specify the invocation name for each country that you plan to make your skill available. If you plan to offer your skill on the Amazon Echo Show, click the check box, and then enter the web player URI, background image, and logo.

Configure Fire TV support (optional)

Pairing your video skill with a Fire TV app, Alexa-enables your app. If you plan to pair your Fire TV app with your video skill, enable Fire TV support and enter your app name in the developer portal. Add the client ID associated with your Fire TV app from the API Key in your LWA security profile. This configuration authorizes the skill to communicate with your app.

After you complete the Fire TV support section, the account linking and permissions configuration isn't required.

Step 2: Implement skill code

You implement your smart home skill code as an Amazon Web Services (AWS) Lambda function. For more details, see Implement Video Skill Code.

Step 3: Configure account linking

All video skills must enable account linking to connect the identity of the Alexa user with the user's identity in your system. For a video service, your system might have a user account that store's the user's service level, such as which videos are free. When the user enables your skill in the Alexa app, Alexa starts the account linking process and receives an access token from your system. Later, when the user asks Alexa to play the video, Alexa sends the access token to your skill. The token enables your skill to access the user's account in your system to know whether they have access to the video.

Alexa uses OAuth 2.0 authorization code grant type for smart home and video skills. To configure account linking, you need the following information from your OAuth provider. For details about these fields, see Configure an Authorization Code Grant.

  • URI of the login page on your authorization server — When a customer enables your skill in the Alexa app, Alexa redirects the customer to this URI to enter login credentials. On successful login, the server returns an authorization code to Alexa.
  • URI of your access token server — Endpoint of your authorization server that can exchange an authorization code for access tokens.
  • Client ID — Unique string that identifies the skill that makes requests to your resource server on behalf of the Alexa user.
  • Your client secret — Alexa uses the client ID and client secret to authenticate with the Access token URI. These credentials identify the request from Alexa.
  • Authentication scheme — Identifies the type of authentication that Alexa uses to request access and refresh tokens from your access token server.
  • Scope — (Optional) List of credentials to request from the skill user, such as user id and password. You can provide up to 15 scopes.
  • Domains — (Optional) List of domains that the authorization server requests content from. You can provide up to 30 domains.
  • Default access token expiration — (Optional) If your server doesn't provide the expiration time for access tokens in the messaging, you must provide the number of seconds for which the access token is valid.

You configure the authorization server and security profile for the skill in the Alexa developer console. On the Smart Home page, from the left menu, click ACCOUNT LINKING. Enter the required information, and then click Save. You can see the redirection endpoints that Alexa uses in the Alexa Redirect URLs field. Register these redirection URLs with your authorization server.

You can use the Amazon OAuth authorization server, called Login with Amazon (LWA) or your own OAuth 2.0 provider. For details about how to set up account linking with the LWA authorization server, see Smart Home Tutorial Step 4: Set up Account Linking.

Step 4: Test your skill

As you develop your skill code, you can create test cases in the Lambda console to test the request from Alexa. For details, see Smart Home Tutorial: Step 2e: Test Your Lambda Function.

When your implementation is complete, you can enable your skill and begin testing.

To enable your skill and begin testing

  1. In the Alexa app, enable your skill. Alexa performs account linking, sends an Alexa.Authorization.AcceptGrant to your skill to connect your skill to the user's Amazon account, and then sends an Alexa.Discover request to your skill to discover devices.
  2. If your skill successfully discovers devices, in the developer console, complete the steps to enable your skill for testing.
  3. In the developer console, on the Test tab, test your skill in the Alexa Simulator.
    Give Alexa commands using the friendly names found in your discovery response and in the Alexa app. Use utterances specific to the device capabilities that your skill supports. Make sure to test your skill with valid and invalid utterances. To verify change reporting and endpoint health, power your device off and back on.

You can iterate on your skill code and continue testing. If you change the account linking configuration, disable and re-enable the skill in the Alexa app to test the new changes. If you change your discover response code, make sure that you disable and re-enable your skill in the Alexa app. For options to test and debug your skill, see Test and Debug Your Smart Home Skill.

When you're satisfied with your skill, you can provide the skill distribution information.

Step 5: Provide publishing information

To distribute your skill to the Amazon Alexa Skills Store, you must fill out the required metadata for your skill on the Distribution tab in the developer console. The information you provide displays with your skill in the Alexa app.

After you complete and save the skill information, you can distribute your skill for beta testing or submit it for certification. For details, see Smart Home Skill Publishing Guide.

Step 6: Beta test your skill (optional)

You have the option to set up a beta test for your skill. With a beta test, you make your skill available to a limited group of testers that you personally select, rather than to the public. For details, see Skills Beta Testing.

Step 7: Submit your skill for certification

When you're ready to publish your skill, submit for certification. For details about certifying a skill, see Test and Submit Your Skill for Certification.

To submit your skill for certification

  1. Run the validation tests on the Certification page in the developer console. These tests help you identify issues that you must fix before you submit the skill.
  2. Make sure that your skill meets the Alexa policy guidelines. These guidelines help make sure that your skill is appropriate for all customers. Adherence to these guidelines guards the privacy and welfare of Alexa users.
  3. Make sure that your skill meets the Alexa security requirements. Customer trust is important. To protect customer data, your skill must meet these security requirements.
  4. When you're ready for your skill to be made public, and you verified that your skill meets the policy and security requirements, submit your skill for certification.

Revise and update your skill after publication

After Amazon publishes your skill to end users, the skill status changes to live. Any changes that you make to the skill configuration and the Lambda function must be recertified. When the skill status changes to live, a new development version is automatically created in the Alexa developer console. This version has the same information as the original live version. You make changes to the development version. 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. For details, see Revise and update your skill in the developer console.

To change to your Lambda function skill code

  1. Create a new Lambda function with a new ARN.
  2. Copy your live Lambda function skill code to the new Lambda function.
  3. In the new Lambda function, make updates to your skill code.
  4. In the development stage for your skill, update the Lambda ARN configuration to point to the new Lambda function ARN.

After Amazon certifies your updated skill, Alexa sends requests to the new Lambda ARN. You can deprecate the previous Lambda function or use the function for future development or updates.