Thank you for your visit. This page is only available in English at this time.

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 directives without jumping into their own app to make changes. We provide a sample 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.

If desired, you can also make updates directly to your own Fire TV app here, without using the sample app. The documentation here provides a mixed flow that accommodates both scenarios — using the sample app or using your own app.

About the Sample App

The sample app is a fork of Fire App Builder, which is a Java-based Android toolkit for building Fire TV apps. This fork incorporates a working video skill. To accomplish this, the app incorporates Amazon Device Messaging (ADM) and the Alexa Client Library. 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 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.

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 1.8 version of Java Development Kit (JDK) or greater 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 build tools or APIs that you're missing.

Download Sample Fire TV App

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.

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 to the directory where you downloaded the sample app. Select the Application folder, and then click Open.

    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.

    Additionally, you might see "Invalid VCS root mapping." Remove the project's .git folder (invisible), and this prompt should go away.

    The first time you open the project, it can take anywhere from 20-40 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 take about a minute or less. If Android Studio is missing any needed libraries or files, you might see messages such as the following:

    If you see these messages, click these links to install the missing tools. Simply keep opening the project and installing any missing tools as prompted until Android Studio no longer complains.

    If you run into build failures, you can try cleaning and rebuilding the project (Build > Clean Project or Build > Rebuild Project).

  4. Open the Gradle Console by clicking the Build button in Android Studio's footer so you can monitor the progress of the Gradle Build. This will let you know if the build succeeds or if Android Studio requires other downloads. Wait until Gradle finishes building.

    When Gradle finishes building the project, Android Studio will show the following directories in the Android view:

    Android Studio directories with Alexa Client Library included

    Notice that one of the directories is AlexaClientLib, which includes the Alexa Client Library. (This directory is not included in the default Fire App Builder project.)

    Also note that when Android opens the project, by default the Android view is shown (circled in red in the previous screenshot), and the "Application" folder is simply referred to as "app."

Customize the Video Skill ID

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

  1. Press Shift twice and search for TenFootApp.java.
  2. Customize the value for ALEXA_SKILL_ID with your own video skill ID. For example:

    private static final String ALEXA_SKILL_ID = "amzn1.ask.skill.544641fd-b4b3-40ab-a9f6-c9757bda68b6";
    
  3. Note the following line:

    clientManager.setAlexaEnabled(true);
    

    This service prompts the VSK client library to auto-pair your Fire TV app with your video skill as soon as possible. (If you have this line commented out (as was the case in previous versions), uncomment it.)

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. Go to app > manifests and open the AndroidManifest.xml file. Update the package name com.fireappbuilder.android.calypsovsk name to a unique package name, such as com.fireappbuilder.android.mycompany:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.fireappbuilder.android.calypsovsk">
    

    The sample app doesn't have any classes in the com.fireappbuilder.android.calypsovsk package.

  3. Expand Gradle Scripts in the sidebar and open the build.gradle (Module: app) file. Update the applicationId property to match your package name. For example:

    defaultConfig {
        applicationId "com.fireappbuilder.android.calypsovsk"
        minSdkVersion 21
        targetSdkVersion 23
        versionCode 10
        versionName "1.0.7"
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
        multiDexEnabled true
    }
    
  4. Go to TVUIComponent > manifests and open the AndroidManifest.xml file. Change every instance of the package name to your unique package name. There are several instances to change:

    <permission
        android:name="com.fireappbuilder.android.calypsovsk.RECEIVE_ADM_MESSAGE"
        android:protectionLevel="signature" />
    
    <uses-permission android:name="com.fireappbuilder.android.calypsovsk.RECEIVE_ADM_MESSAGE" />
    ...
    <intent-filter>
    <action android:name="com.amazon.device.messaging.intent.REGISTRATION" />
    <action android:name="com.amazon.device.messaging.intent.RECEIVE" />
    <category android:name="com.fireappbuilder.android.calypsovsk" />
    
  5. Go to ContentBrowser> res > values and open custom.xml. Change the package name in the following line:

    <!--Your package name, should be same as in AndroidManifest--&>
    <string name="launcher_integration_intent_package_value">com.fireappbuilder.android.calypsovsk</string>
    
  6. When you make changes to Gradle files, you might be prompted to synchronize Gradle with your project. If prompted, click the Sync Now link in the upper-right corner.
  7. Go to Build > Rebuild Project to clean up any artifacts from the previous app and then rebuild your project.

    With this sample app, don't worry about warnings such as "Configuration 'compile' is obsolete and has been replaced with 'implementation' and 'api'." The app will still build. These updates will be made in a future version of this sample app.

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.)