Step 2: Set Up the Sample Fire TV App (VSK Fire TV)

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
Android Studio
Download Sample Fire TV App with VSK
Open the Sample App in Android Studio
Replace the Package Name in the Sample App
Customize the Video Skill ID
Identifying Sample App Instructions
Next Steps

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.

Android Studio

To work with the sample app, you need to install Android Studio, the official IDE for Android projects. Android Studio includes a bundled version of the JDK, which compiles the Android projects into APKs. 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:

Go to https://github.com/amzn/sample-fire-tv-app-video-skill.
Click Code > Download ZIP.
Save the zip file to a convenient location and then unzip it.
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:

Start Android Studio.
At the Welcome dialog, click Open an existing Android Studio project.
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.

Tip: While the build processes, 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.

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

If you run into build failures, you can try rebuilding the project by going to Build > Rebuild Project.
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

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.

Important: When Android opens the project, by default the Android view is shown (circled in red in the previous screenshot). The instructions in this documentation will assume that you're working in this Android view.

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:

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

This will show the com.example.vskfiretv package in a hierarchy, with com > example > vskfiretv expanded.
Right click example and select Refactor > Rename.
Select a unique name (such as your name) and then click Refactor.
Click Do Refactor.

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" />

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.
Go to Build > Rebuild Project.

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

Note: You can't run your app on a Fire TV device at this point because the Alexa Client Library requires a security profile to run. You will connect to Fire TV in Step 8: Test Your Skill and Observe Logs. For now, just make sure you can build the project locally in Android Studio.
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:

Go to app > java > com > example > vskfiretv > MainActivity (the path will differ based on how you customized the package name).
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 for Cloudside Integrations.)

Last updated: Oct 13, 2021