Video Tutorial
The following is a high-level video tutorial about integrating the VSK into your Fire TV app using the app-only integration:Voice Capabilities with Catalog Integration
A prerequisite to integrating your app with the VSK is to first ingest your catalog and then integrate with Fire TV’s universal search and browse (also referred to as “launcher integration”). When you complete this catalog integration, your customers receive app launch capabilities and implicit quick play. For example, customers can say the following:- App launch: “Open <app name>”
- Implicit quick play: “Watch <video name>”
Voice Capabilities with VSK Integration
By integrating the VSK with your app, you can give your customers many more voice capabilities, allowing customers to more easily discover, find, and engage with content in your app (without relying on a remote). When you integrate with the VSK, Alexa delivers the requests directly to your app (in the form of JSON-based information blocks called “directives”) so that you can process the requests with your own app’s logic. This gives you more control and capability about how to interact with customer’s requests (called “utterances”). When you integrate with the VSK, there are two primary VSK interfaces you interact with:SearchAndPlay (which includes “watch/play …” requests) and SearchAndDisplayResults (which includes “search/find …” requests). The API reference describes the full list of utterances supported by these interfaces and the directives they send to your app. In addition the app launch and implicit quick play (already provided with catalog integration), here are a few examples of requests that customers can say when you integrate the VSK.
| Feature | Utterance or Example |
|---|---|
| Watch title (explicit) | “Watch <video name> on <app name>“ |
| Search by genre | ”Find <genre name>“ |
| Search by actor | ”Search for <actor name> movies” |
| Watch by franchise | ”Watch <franchise> on <app name>“ |
| Search by production company (explicit) | “Search for <production company> on <app name>“ |
| Watch by sports type | ”Watch <sports type>“ |
| Watch by season and episode | ”Watch <TV show> season 2, episode 3 |
| App foreground/background state contextual search disambiguation | User: “Watch <comedies>“ App in foreground: (Alexa) “Here are some comedies” App in background: (Alexa) “I can do that on <app 1> or <app 2>, which would you like?” |
| Multi-turn capability | (following disambiguation) (User) “<app 2>“ (Alexa multi-turn) “Okay, here’s <genre name> on <app 2>“ |
| Feature gate by user state | Add or remove app capabilities based on user or app state changes |
SearchAndPlay and SearchAndDisplayResults for a more comprehensive list of utterances and the directives sent. Or if you just want to browse utterances by directive, see the Utterances Reference.
Expectations in Handling Directives
As you integrate your app with the VSK, you should understand what directives your Fire TV app will receive and how you’re expected to handle them. A directive is a set of data and instructions, expressed in JSON, sent from Alexa to your app. For example, the directive might be to search for a TV show or play a movie. If a user says, “Watch Batman,” Alexa sends your app aSearchAndPlay directive with the following payload:
transcribed is a reduced version of the phrase the customer used in the request. uri is your catalog’s identifier for the media. type indicates that this media is part of a franchise (“franchises” are movies with sequels). The payload objects are defined in detail in the corresponding API Reference.
Alexa sends these directives to your app, and you’re expected to react to the directive (e.g., show results for a request, or play the requested video). This documentation will describe the directives but not provide detailed instruction on how to handle the directives in your app — that logic is something you need to develop on your own.
VSK Implementation Options: App-only or Cloudside
You can implement the VSK into your Fire TV app in two different ways:- App-only integration: Receive directives delivered directly in your app. A service on Fire TV called the VSK Agent routes directives from Alexa to your app by way of broadcast intents. A BroadcastReceiver in your app handles the intents. (This implementation, which uses intents and BroadcastReceivers, follows a pattern similar to catalog integration.)
- Cloudside integration: Receive directives to a Lambda function in AWS and then send the directives (or the result after processing the directive) to your app through a messaging service (usually Amazon Device Messaging). Your app authorizes the incoming message and then handles the request.
Sample Apps
Both app-only and cloudside integrations have sample apps (based on Android TV Leanback library) demonstrating the integration (see the app-only sample app and the cloudside sample app). Given that VSK implementations can be lengthy, many partners want to explore how the VSK works (and see directives hitting the app or Lambda) in an immediate way to better understand expectations. The sample apps provide a quick way to explore VSK-integrated apps and also serve as a reference for the integration. In this documentation, instructions related to sample apps often appear in callouts like this:What You’ll Need
To complete the VSK integration, you’ll need the following:- Fire TV device. You can use any Fire TV device to test the integration. You can use the microphone button on the Fire TV device’s remote control to make voice requests to the TV. (If your remote control doesn’t have a microphone, you can pair an Echo to your Fire TV.) The recommended Fire TV is Fire TV Stick 4K, but any Fire TV device will work.
- Android app. You need a native Android app that can play streaming media. If you don’t have an app, or if you want to explore the VSK through a sample app, sample apps are available.
- Catalog integration. You need to integrate your catalog before you can complete the VSK integration. If you haven’t started this yet, you can use the sample app’s catalog during development.
- Amazon developer account. You need an Amazon developer account (it’s free). If you don’t already have an account, go to developer.amazon.com, click Sign In in the upper-right corner, and then click Create your Amazon Developer account.

