Developer Console

Step 2: Set Up the Sample Fire TV App

Most developers integrating the VSK already have a robust Fire TV app. However, many times developers want to explore the VSK workflow and see the incoming ALEXA directives without jumping into their own app to make changes. We provide a basic Fire TV app that already has some configuration and setup to show a working video skill. You can use this sample app to explore the VSK, and then later, after you've finished exploring how the VSK works, you can go back through this same process with your real app.

Alternatively, if desired, rather than editing the sample app first, you can also make updates directly to your real Fire TV app instead. The documentation here provides a mixed flow that accommodates both scenarios — updating the sample app or using your own app.

About the Sample Fire TV App with VSK

The sample app is basic Android app that incorporates a working video skill to play streaming video. To accomplish this, the app incorporates the Alexa Client Library and Amazon Device Messaging (ADM). Once configured, the app plays up a video when you ask Alexa for the video by title. You'll still need to configure the sample app with your package name and video skill.

The sample app will allow you to see a directive pushed to the app. This preview can give you more of a sense of how the video skill will interact with your app. The sample app does not show logic about how to handle the directives to perform specific actions in the app — you'll need to work out much of the logic on your own based on your own unique code.

Additionally, this sample app is meant as a companion to the documentation, not as a starting point or template for your own app. Almost every video partner that integrates the VSK already has a custom-developed app. The sample app simply provides some context for some of the integration instructions.

You won't be running the sample app until a later step (Step 8: Test Your Skill and Observe Logs in CloudWatch ). When you do, the sample app will look like this:

Several common videos are integrated into the sample app.
Several common videos are integrated into the sample app.

Prerequisites

To work with the sample app, you will need the Java Developer Kit (JDK) and Android Studio. Experienced Android developers likely already have this set up. If so, you can jump down to Download Sample Fire TV App.

Java Development Kit

You need the Java Development Kit (JDK) from Oracle. The JDK is used to compile Java apps on your machine as well as perform other tasks (such as using keytool). First, check to see if you already have the JDK:

  1. Open a terminal or command prompt.
  2. Type java -version. If you have the JDK, the response should be something like this:

    openjdk version "12.0.2" 2019-07-16
    OpenJDK Runtime Environment (build 12.0.2+10)
    OpenJDK 64-Bit Server VM (build 12.0.2+10, mixed mode, sharing
    

    On Windows you can also manually look in a directory such as C:\Program Files\Java\jdk1.8.0\ to see if the JDK is there.

  3. If you don't have the JDK, download the appropriate version of the JDK Installer for your machine from Java SE Development Kit Downloads and run it. For more details, see the following:

Android Studio

To work with the sample app, you need to install Android Studio, the official IDE for Android projects. See Getting Started with Android Studio and Install Android Studio for information about setting up the Android Studio development environment on your machine.

The sample app requires you to have certain SDK tools and APIs installed with Android Studio. Selecting these tools from the Standalone SDK Manager ahead of time isn't necessary. When you open the sample app project, Android Studio will prompt you to install any missing build tools or APIs.

Download Sample Fire TV App with VSK

To download the sample app:

  1. Go to https://github.com/amzn/sample-fire-tv-app-video-skill.
  2. Click Clone or download. Then click Download ZIP.
  3. Save the zip file to a convenient location and then unzip it.
  4. If desired, remove the .git folder, since Android Studio will attempt to identify the VCS mapping.

The repository contains two folders:

Folder Contents
VSKFireTV-sample-app A sample Android project with the Video Skills Kit configured, including the Alexa Client Library and ADM JAR files
Lambda A Node project (index.js and package.json) for creating the Lambda deployment package described in Step 6: Create and Deploy a Lambda Package. The folder also contains video_catalog.json that provides an example of a data source for the video content.

Open the Sample App in Android Studio

Open the project in Android Studio and build the app:

  1. Start Android Studio.
  2. At the Welcome dialog, click Open an existing Android Studio project.
  3. Browse and select the parent directory (e.g., sample-fire-tv-app-video-skill) that contains the "app" directory, and then click Open.

    When you first open the project, Android Studio might detect an incorrect location for the Android SDK and suggest a path mapped to your machine. Accept the suggestion. Additionally, you might see "Invalid VCS root mapping." Remove the project's .git folder (invisible), and this prompt should go away.

    Gradle starts building the project. Depending on the latest release of Gradle, you may be prompted to update Gradle. If prompted, click Don't remind me again for this project.

    The first time you open the project, it can take several minutes for Gradle to build the project, depending on the assets Gradle needs to download as well as your network and processor speed. Subsequent times should be faster. If Android Studio is missing any needed libraries or files, you'll be prompted to install them. If prompted, install any required tools.

    When Gradle finishes building the project, you should see a green check mark in the Build tab to indicate success.

    Successful build
    Successful build

    If you run into build failures, you can try rebuilding the project by going to Build > Rebuild Project.

  4. Click the Project side tab on the left side to view the project files. Android Studio will show the following directories in the Android view:

    Android view of the sample app project
    Android view of the sample app project

    Notice that one of the directories is AlexaClientLib, which includes the Alexa Client Library. In the Project view, the app directory contains a libs folder that contains the Amazon Device Messaging JAR.

Replace the Package Name in the Sample App

You need to replace the package name in the sample app. Package names must be unique in the Appstore, and later configurations with security profiles and API keys in the Developer Portal will require a unique package name. The following code samples show the package name that needs customization in bright red. To customize the package name:

  1. Make sure you're in the Android view (as described in the previous section).
  2. Click the Options menu (gear icon) and clear the check next to Compact Middle Packages.

    Compacting middle packages

    This will show the com.example.vskfiretv package in a hierarchy, with com > example > vskfiretv expanded.

  3. Right click example and select Refactor > Rename.

    Renaming the package
  4. Select a unique name (such as your name) and then click Refactor.

    Refactoring
  5. Click Do Refactor.

    Doing the refactor
  6. Go to app > manifests and open the AndroidManifest.xml file. Update each instance of the package name com.example.vskfiretv to your package name. There are several instances in AndroidManifest.xml to update. Most of these instances should have been updated when you did the refactoring in the previous steps. But if the old package names still persist, update them:

    line 5:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:amazon="http://schemas.amazon.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.vskfiretv">
    

    lines 9 and 12:

    <permission
        android:name="com.example.vskfiretv.permission.RECEIVE_ADM_MESSAGE"
        android:protectionLevel="signature" />
    <uses-permission
        android:name="com.example.vskfiretv.permission.RECEIVE_ADM_MESSAGE" />
      

    line 66:

     <category android:name="com.example.vskfiretv" />
     
  7. Expand Gradle Scripts in the sidebar and open the build.gradle (Module: app) file. Update the applicationId property with your unique package name:

    line 21:

     applicationId "com.example.vskfiretv"
    
  8. Go to app > res > values > strings.xml and update the app name with a unique name:

    line 2:

    string name="app_name">VSKFireTV</string>
    
  9. Expand Gradle Scripts and open build.gradle (Module: app). Update the applicationId value with your unique package name:

    line 15:

    defaultConfig {
    applicationId "com.example.vskfiretv"
    minSdkVersion 23
    targetSdkVersion 29
    versionCode 1
    versionName "1.0"
    

    When you update your build.gradle file, Android Studio prompts you to resync your project, so you can click Sync now.

  10. Go to Build > Rebuild Project.

    After the build is complete, a message appears that says "Gradle build finished."

  11. Make note of your package name in the same file where you stored your video ID, as you will need this name later when you create a security profile.

Customize the Video Skill ID

You need to configure the video skill ID in the sample app:

  1. Go to app > java > com > example > vskfiretv > MainActivity (the path will differ based on how you customized the package name).
  2. Find final String alexaSkillId and replace the value with your video skill ID you created in Create a Video Skill in Step 1.

    line 102:

    final String alexaSkillId = "amzn1.ask.skill.12345678-abcd-1234-efgh-123456789";
    

    Note the following on line 118:

    // Initialize the client library by calling initialize().
    clientManager.initialize(getApplicationContext(),
       alexaSkillId,
       AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
       capabilities);
    

    This service prompts the VSK client library to auto-pair your Fire TV app with your video skill as soon as possible. Later in Step 12: Go Live! you will change SKILL_STAGE_DEVELOPMENT to SKILL_STAGE_LIVE.

Identifying Sample App Instructions

The documentation calls out specific info along the way for working with the sample app. Often the documentation will put information related to the sample app in a callout like this:

Sample App Instructions

Instructions for working with the sample app often appear formatted like this. Unless you see this callout, continue through the normal documentation steps. The callout might let you know that the current steps aren't required because the code is already implemented in the sample app. Or the callout might give you special instructions or information for working in the sample app.

Next Steps

Now that you have the sample app set up, go to Step 3: Integrate the Alexa Client Library.

(If you run into any issues that prevent you from continuing, see Troubleshooting.)