About the VSK Agent
The VSK Agent is an on-device routing agent on Fire OS. Your Fire TV app uses theVSKAgentClient class to report its dynamic capabilities to the VSK Agent. These capabilities let the VSK Agent know what kind of directives it can broadcast to your app. The VSK Agent communicates with Fire OS through the Android Interface Design Language API, or AIDL.
The VSK Agent will send only directives that your app is capable of supporting. For example, if you don’t indicate that your app is capable of supporting the PlaybackController interface, Alexa won’t send you PlaybackController directives.
Choose How to Integrate with the VSK Agent
You have two options for how you integrate with the VSK Agent:Option 1: VSK Agent Client Library (recommended approach)
The recommended approach is to consume the Amazon-provided VSK Agent Client Library. The VSK Agent Client Library gives you the full functionality of VSK Agent while streamlining some of the Android interprocess communication (IPC) details. The VSK Agent Client Library reduces your need to write many lines of code for integrating with the Fire TV VSK Agent. In short, it handles the work of connecting to this service for you, presenting you with normal Java methods you can call. When you consume the VSK Agent Client Library, you have the ability to dynamically add or remove capabilities selectively and at any time. If you plan to support more advanced ways of communicating your app’s UI state or other dynamic state updates in the future, you should choose this option. Leveraging the VSK Agent Client Library to integrate with VSK Agent is the fastest and easiest route to enable VSK capabilities in your app. (Note that even with the VSK Agent Client Library, capabilities which are always supported can still be declared in a static resource by following the static capabilities integration.) The VSK Agent provides two methods for reporting your app’s capabilities in a dynamic way:AddOrUpdateCapabilities()— a method for declaring the capabilities you support.sendCapabilityTestDirective()— a method for testing your integration.
Option 2: VSKApplicationAgentAPI
Another option for connecting with the VSK Agent is for you to consume only the service definition and manage this connection code yourself. The VSK Agent Client Library communicates with a bound service under the hood. If you so choose, you can integrate with this under-the-hood service yourself by consuming theVSKApplicationAgentAPI package yourself.
This VSKApplicationAgentAPI package contains the necessary .aidl files (as part of the Android Interface Definition Library) and Java classes for communicating with this service. While not the recommended route, Amazon realizes that under certain circumstances, you may want to manage all code yourself. This option might be appealing if you do not want to have any Amazon libraries or code in your project, perhaps to avoid any dependencies or due to other requirements.
See Steps for Option 2: Integrate with VSK Agent through VSKApplicationAgentAPI Package for some brief steps. More details about how to consume the VSKApplicationAgentAPI package in detail are beyond the scope of this documentation.
Steps for Option 1: Integrate with the VSK Agent Service via the VSK Agent Client Library
To integrate with the VSK Agent Client Library to communicate with the VSK Agent (Option 1), perform the following steps:Add the VSK Agent Client Library to Your Project
- Download the VSK Agent Client Library (an AAR file): Note that by downloading the VSK Agent Client Library, you agree to Amazon’s Program Materials License Agreement. (Note that the “VSK Agent Client Library” is not the same as the “Alexa Client Library” used in cloudside integrations.)
- Add the VSK Agent Client Library to your project. In Android Studio, go to Find > New > Module. Then choose Import .JAR/.AAR Package and select the VSKApplicationAgentClientLibrary file.
-
When you import the AAR file, Android Studio adds VSKApplicationAgentClientLibrary to
settings.gradle (Project Settings)so that it is available to be added as a dependency in your app’sbuild.gradlefile. Expand Gradle Scripts and go tosettings.gradle (Project Settings). Make sure theVSKApplicationAgentClientLibraryhas been included: -
Expand Gradle Scripts, open
build.gradle (Module: App), and add a dependency for theVSKApplicationAgentClientLibraryin thedependenciesobject:Note that the VSK Agent Client Library is not available on Maven or JCenter.
Configure Your Manifest
Your app’s manifest (AndroidManifest.xml) contains declarations of the activities that your app performs. In your app’s manifest, add the following permission to allow your app to integrate with VSK Agent:
Initialize the VSK Agent Client Library
The next step is to initialize the VSK Agent Client Library within your code base.-
Create a new instance of the VSK Agent client:
-
Declare your capabilities in the
reportDynamicCapabilities()method, and then make a capability reporting request with theAddOrUpdateCapabilities()method. Call this method in your app after the user has logged in.Alexa will send directives related to these capabilities listed here. For example, if you indicateremote_video_player_capability, Alexa will send directives related to theRemoteVideoPlayerinterface. If you don’t have the capability declared, Alexa won’t send directives related to the capability. -
The previous code declares capabilities by referencing files with code such as
Utils.getTextForRawResource(R.raw.remote_video_player). The references in the previous sample code are as follows:remote_video_player_capability(refers toRemoteVideoPlayer)seek_controller_capability(refers toSeekController)play_back_controller_capability(refers toPlaybackController)keypad_controller(refers toKeypadController)channel_controller_capability(refers toChannelController)
app/res/raw, create the necessary files with these names and capabilities declarations based on the interfaces your app supports. The details of the JSON objects for each of the capabilities are described in Supported Capabilities with App-only Integration. -
Using the the
addOrUpdateCapabilities()method, report your app’s dynamic capabilities to the VSK Agent:Now the VSK Agent will know that your app supports those capabilities. When you later run your app on Fire TV and look at the logs (in Step 10: Test Utterances and Observe Logs), you will see these capabilities reported to the VSK Agent by theDynamicCapabilityReporterclass.
Full Code Example for Reporting Dynamic Capabilities
Here’s a full boilerplate code example for reporting dynamic capabilities.Steps for Option 2: Integrate with VSK Agent through VSKApplicationAgentAPI Package
If you prefer to integrate with the VSK Agent yourself using theVSKApplicationAgentAPI package (without relying on the VSK Agent Client Library), do the following:
- Download the VSKApplicationAgentAPI (an AAR file). Note that by downloading the VSKApplicationAgentAPI, you agree to Amazon’s Program Materials License Agreement.
- Add the VSKApplicationAgentAPI to your project. In Android Studio, go to Find > New > Module. Then choose Import .JAR/.AAR Package and select the VSKApplicationAgentAPI file.
-
When you import the AAR file, Android Studio adds the file to
settings.gradle (Project Settings)so that it is available to be added as a dependency in your app’sbuild.gradlefile. Expand Gradle Scripts and open thesettings.gradle (Project Settings)file. Make sure theVSKApplicationAgentAPIhas been included: -
Expand Gradle Scripts and go to
build.gradle (Module: App)and add a dependency for theVSKApplicationAgentAPIin thedependenciesobject: - Declare the necessary permissions in your app manifest.
-
On application create, report the currently supported capabilities via the
addOrUpdateCapabilities()method. -
Whenever an app state change would cause your supported capabilities to change, also call
addOrUpdateCapabilities().
Best Practices: Dynamic Capability Reporting
When you report dynamic capabilities to the Alexa App Agent, it determines if your app’s capabilities have changed since the previous report, and then reports any changes to the Alexa cloud. For that reason, it’s a good idea to report your dynamic capabilities on every app start. However, these capabilities should not change across reports. Changes in dynamic capabilities should be reported when there are long term changes in the application or the customer state that impacts the ability to handle customer requests. For example, you may remove the capability to play content when the customer logs out of your app. Reporting changes in your dynamic capabilities causes unnecessary churn in the capabilities reported to Alexa, and may impact your customers. This is especially true if your app is throttled due to excessive discovery traffic. To avoid this, we highly recommend you follow these guidelines when reporting dynamic capabilities:- Don’t report capabilities based on an unknown state. For instance, if the dynamic capabilities your app reports depend on if the user is logged in and that is determined asynchronously, wait until that state is known before reporting. Don’t report dynamic capabilities as if the customer was logged out only to report again a few moments later.
- Don’t report capabilities based on an ephemeral state that may change frequently. For example, you don’t need to add or remove
PlaybackController/SeekControllerbased on if content is playing or not. It is enough that your app is capable of the actions declared by the capability interface. - Don’t add or remove capabilities based on the state outside your application logic. For instance, it’s not necessary to change your app’s capabilities based on if your app is in the foreground, or if a customer switched inputs on FireTV.

