Developer Console
Sign In
Sign In
Developer Console

App-only Integration Overview

With the app-only implementation for VSK, the Alexa Video Skill API sends directives directly to your app on Fire TV device. Fire TV has a service called the "VSK Agent" that receives the Alexa directives and broadcasts them as an intent, which your app then handles through a BroadcastReceiver. The entire VSK integration is done directly within your Android code.

Components

The following components are involved in the app-only integration:

  • VSK Agent — A service built into the Fire OS on Fire TV that receives Alexa directives and broadcasts them as intents to apps on Fire TV. (All Fire OS versions are supported.)

  • Fire TV. The device on which you run your app. Your Fire TV needs to have a microphone button on the remote control to make voice requests. The recommended Fire TV is Fire TV Stick 4K, but most Fire TV device will work.

  • VSK Agent Client Library — An AAR library that is used if your app's voice capabilities change based on the user's login state (referred to as "dynamic capabilities integration"). The VSK Agent Client Library implements the Android Interface Definition Language API (AIDL) to connect to the VSK Agent on Fire OS.
  • VSKApplicationAgentAPI — Optionally used if you don't want to integrate the VSK Agent Client Library but instead want to write the code contained in the VSK Agent Client Library yourself to communicate with the VSK Agent. The VSKApplicationAgentAPI contains the necessary .aidl files and Java classes required for communicating with the VSK Agent on Fire TV.
  • Alexa in the cloud — An Alexa service that receives the customer's request (utterance), performs natural language processing to parse the request and determine the intent, and then packages it up into a directive (JSON-block) that can be handled by the Video Skill API.
  • Alexa Video Skill API — A service that sends directives from Alexa in the cloud to the Fire TV VSK Agent, which then broadcasts the directives as an intent. Different interfaces handle different types of directives. You can browse more details here: API Reference Overview.
  • Your Android app — A native Android app that can show streaming media content to users. If you don't already have an app, you can use the sample app as a starting point (otherwise, use it for reference as you write your own code).
  • BroadcastReceiver class — The class in your app where you accept and handle the directives Alexa sends to your app by way of the VSK Agent on Fire TV.
  • DynamicCapabilityReporter class — The class in your app that reports capabilities based on the user state. As part of the VSK Agent Client Library initialization, this class creates an instance of the VSK Agent client.

High-level Workflow

The high-level workflow for app-integrations is as follows:

  1. A customer says a request to Alexa. Alexa in the cloud interprets the request as a specific type of utterance and packages the information into a directive.
  2. Alexa routes the directive to a Fire TV device by way of the Video Skill API. Different interfaces in the Video Skill API handle different types of directives. The primary interface is RemoteVideoPlayer, which sends two types of directives: SearchAndPlay directives and SearchAndDisplayResults directives. SearchAndPlay directives are "watch/play …" requests, while SearchAndDisplayResults directives are "search/find …" requests. (Although the Video Skill API has more interfaces, only RemoteVideoPlayer is recommended for Fire TV partners.)
  3. On Fire TV, a service called a VSK Agent receives the Alexa directives and broadcasts them as an Android intent. The intent is a packet of information that indicates an operation or action that needs to be performed.
  4. Your app's manifest contains an intent filter and a BroadcastReceiver. The intent filter (declared in your app's manifest) specifies that your app is listening for intents from the VSK Agent (it filters the intents to these types). The BroadcastReceiver specifies the particular receiver that can handle the intents. When the VSK Agent broadcasts an intent containing an Alexa directive, your app handles the intent.
  5. The logic in your BroadcastReceiver reads the directive and handles it accordingly (such as getting the requested video the customer requested). You are responsible for writing the logic to handle the requests.
  6. Your BroadcastReceiver sends a message (a PendingIntent) back to the VSK Agent to let it know your app processed the directive successfully. The response status is a Boolean indicating whether the directive was handled successfully or not.

Integration Steps

The process for performing the app-only integration involves the following steps:

 VSK App-only Integration

STEP 1:
Integrate Your Catalog
→
STEP 2:
Integrate with MediaSession
→
STEP 3:
Set Up the Sample App
→
STEP 4:
Decide on the Integration Type
→
STEP 5:
Report Your App's Static Capabilities
→
STEP 6:
Report Your App's Dynamic Capabilities
→
STEP 7:
Add a Broadcast Receiver
→
STEP 8:
React to Directives
→
STEP 9:
Sign Your App and Configure a Security Profile
→
STEP 10:
Test Utterances and Observe Logs

Video Tutorial

This video tutorial provides an overview about integrating the VSK into your Fire TV app using the app-only integration method.

Sample App

To demonstrate the integration, a sample Fire TV app is included with some basic logic to parse messages and play matching catalog titles. You aren't required to use this sample app in the implementation steps — you can perform the same steps using your own app. However, the sample app will provide more clarity about the integration, giving you a reference that you can consult to see more context and detail about the implementation instructions.

If you're just setting up the sample app to get a sense of how the VSK works, you can skip the coding tasks in steps 5, 6, 7, and 8, since the sample app already has this code integrated. However, one purpose of the sample app is to provide a working example of a real-world integration of the instructions, so even though you can skip those steps, you should browse the code in the sample app as a reference for developing your own app's code.

When working with the sample app, be on the lookout for callouts like this:

Sample App Notes

Callouts like this in the integration instructions will indicate what's required with each step with relation to the sample app.

Estimated Development Time

App-only integrations require a lot less development time than cloudside integrations because there are fewer components, and all development is within your Android project. If you already have catalog integration completed, and your app already has logic to handle text inputs for searches and other lookups, the VSK app-only integration can be completed in a short amount of time (a couple of weeks or less).

If you're just exploring the sample app (skipping any coding in your own app), you can get this sample app working in a few hours or less.

Next Steps

To get started, go to Step 1: Integrate Your Catalog.

Last updated: Mar 05, 2021