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

Most developers who are integrating the VSK already have their own Fire TV app. However, many developers want to explore the VSK workflow and see the incoming Alexa directives without jumping into their own app to make changes. A basic Fire TV app with the VSK integrated is available (with a little configuration required). You can use this sample app to explore the VSK, and then later, after you've finished exploring how the VSK works, go back through this same process with your real app. Or you can use this sample Fire TV app as a starting point for your own app.

Sample App Notes

If you're exploring the sample app, be sure to complete all the steps in this topic.

About the Sample App
Download and Install Android Studio
Download and Open the Sample App in Android Studio
Customize the Package Name in the Sample App
Next Steps

About the Sample App

The sample app is basic Leanback-based Android app that incorporates the VSK following the app-only integration model. After a few small configurations, the app plays up a sample video when you ask Alexa for the video by title. The sample app uses the IMDb catalog. As such, when you ask for virtually any movie title or TV show, the sample app should recognize the request as a title within its available catalog. However, the sample app doesn't have rights or video URLs to actually play these titles. Instead, the sample app will play a random video from a small list of generic videos.

The most important aspect of the sample app is that it lets you see an Alexa directive pushed to the app. The sample app does not include extensive logic about how to handle the directives to perform specific actions in the app — you'll need to work out that logic on your own based on your own unique app and content (some details are described in Step 8: React to Directeives). However, most likely you already have these search/play content actions mapped to remote control inputs. To handle the directives Alexa sends, you just need to map the voice inputs to similar actions as the remote control inputs.

In addition to support for SearchAndPlay and SearchAndDisplayResults directives, the sample app supports Play, Pause, and Stop directives from the PlaybackController interface. To see a list of utterances related to these directives, see the Utterances References.

Download and Install Android Studio

To work with the sample app, first download and install Android Studio. 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 computer.

Download and Open the Sample App in Android Studio

To open the sample app in Android Studio:

Go to github.com/alexa/alexa-sample-fire-tv-app-only-integration, click the Code button, and then copy the link to clone the Git project:
```
git clone git@github.com:alexa/alexa-sample-fire-tv-app-only-integration
```
(You can also choose to download the Zip file.)

The repository contains a sample Android project based on the Android Leanback library, including some special classes for interacting with the VSK Agent on Fire TV.
Start Android Studio. At the Welcome dialog, click Open an existing Android Studio project.
Browse to the root directory of the sample app (the directory that contains the "app" directory), and then click Open.

Gradle starts building the project. 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 supporting tools or libraries. If Android Studio is missing any needed files, you'll be prompted to install them. When Gradle finishes, the Build pane will show "Project setup: successful" with a green check mark.
Click the Project side tab on the left side to view the project files. Make sure you're in the Android view.

Important: When Android opens the project, by default the Android view is shown. The instructions in this documentation will assume that you're working in this Android view. You can work in any view you choose, but note that documentation references to file locations will vary in different views.

Customize 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 default package name in the sample app is com.example.vskfiretv.company. In the following steps, you will change the last path to your real company's name so that the package name is unique (e.g., com.example.vskfiretv.acme). Make sure that you keep the initial com.example.vskfiretv path in the package name (otherwise, the catalog for the sample app won't be properly configured to the IMDb-based catalog the backend.)

Note: Customizing the package name is only required with the sample app. This isn't required with your real app. For your real app, leave your package name as is.

To customize the package name in the sample app:

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

This will show the com.example.vskfiretv.company package in a hierarchy, with com > example > vskfiretv > company folders expanded.
Right click company 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.company to your package name (e.g., com.example.vskfiretv.mystreamz).
Expand Gradle Scripts and open build.gradle (Module: app). Update the applicationId value with your unique package name. For example:
```
defaultConfig {
applicationId "com.example.vskfiretv.mystreamz"
minSdkVersion 23
targetSdkVersion 29
versionCode 1
versionName "1.0"
```
When you update your build.gradle file, Android Studio prompts you to resync your project — click Sync now when prompted.
Go to Build > Rebuild Project.

After the build is complete, a message appears: "Gradle build finished." Make note of your package name, as you will need this name later when you create a security profile.

Sample App Notes

You can't run your app on Fire TV yet because the VSK Agent Client Library still needs to be authorized with an API key tied to your app's package name. You'll do that in Step 9: Sign Your App and Configure a Security Profile.

Next Steps

Go to the next step: Step 4: Decide on the Integration Type.

Last updated: Nov 18, 2020