Video Skills Kit (VSK) for Fire TV allows customers to more easily discover, find, and engage with content in your app without relying on a remote. A prerequisite to integrating your app with the VSK is to first ingest your catalog and then integrate with Universal Search and Browse on Fire TV. Catalog integration is currently only available to selected developers. VSK works together with Catalog Integration to surface your content in multiple ways across Fire TV.
VSK allows you to voice-enable the experience in your app. Customers can say "Alexa, watch Batman" (SearchAndPlay) or "Alexa, find Batman" (SearchAndDisplayResults) and Alexa will send a directive to your app, where you can take the customerinto playback or show search results. Customers can skip the use of a verb and simply say "Batman", which is treated by Alexa as a search request. Alexa also supports more ambiguous requests such as "Alexa, find Tom Hanks movies" to find movies by actor, or "Alexa, find comedies" to search by genre.
How does VSK work on Fire TV?
With the App-only implementation for VSK, the Alexa Video Skill API sends directives directly to your app on a 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. If you already have Catalog Integration completed, and your app already has logic to handle text inputs for searches and other lookups, the integration can be completed in a short amount of time (a couple of weeks or less).
Alexa service in the cloud does the hard work of interpreting the customer's request, determining the intent, and then packaging it into a directive so that you can process the requests with your own app's logic. Directives sent to your app contain a structured and resolved representation of the request, where we include entitles such as Video, Actor, Genre and MediaType. See SearchAndPlay and SearchAndDisplayResults for a more comprehensive list of search and play utterances and the directives sent.
Best practices for building a great search experience
Here are some of the best practices for building a great search experience using VSK.
- Declare search as a static capability if your app allows all customers to browse content regardless of the customer’s state (signed in) and other factors (subscription level). Otherwise, you can declare search as a dynamic capability to gate the feature.
- Customers can say “Alexa, find Breaking Bad season 2 episode 3” to search (or watch) a TV series by Season and Episode. You can use Season and Episode fields to take the customer to the episode. If you're missing either season or episode number, you should determine this based on the customer's last watched episode.
- Customers can say "Alexa, find Tom Hanks movies" to find movies by the actor, or "Alexa, find comedies" to search by genre. You have the option to show search results using the Actor, Franchise or Genre fields, or take the customer to special pages dedicated to that particular entity. If your app does not support lookup by these fields, you should fallback to a literal text search of the value sent through in the directive.
- Leverage the SearchText field to help improve the relevancy of results that customers see in your app. For ambiguous requests (those that do not contain a title name), search text will give you an unstructured and more complete view of what the customer has asked - this includes additional entities and unresolved words. For example, "Alexa, watch popular comedy tv shows in HD" will give you the transcribed value "h.d. popular comedy tv shows". Note that there is no word order or formatting guarantee. See SearchText for more information.
- Search results that you present to the customer should include relevant artwork applicable to the titles. The artwork should make it easier for the customer to identify the content you are recommending in the search.
Handling SearchAndDisplayResults directives
Here is a SearchAndDisplayResults directive Alexa might send in response to a customer’s request to search for "Alexa, find Batman".
EXTRA_DIRECTIVE_NAMESPACE: Alexa.RemoteVideoPlayer
EXTRA_DIRECTIVE_NAME: SearchAndDisplayResults
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payloadpayload contains the following:
{
"payload": {
"entities": [
{
"externalIds": {
"ENTITY_ID": "0"
},
"type": "Franchise",
"uri": "entity://avers/franchise/Batman",
"value": "Batman"
}
],
"searchText": [
{
"transcribed": "batman"
}
],
"timeWindow": {
"end": "2016-09-07T23:59:00+00:00",
"start": "2016-09-01T00:00:00+00:00"
}
}
}With VSK integration, you create a BroadcastReciever class in your app. The VSK Agent packages the directive in an intent, which is passed into the onReceive method. With the support of a JSON parser, you can retrieve both the customer’s transcribed search request under transcribed and the entities object, which contains an array of entity objects to search, such as a Title, Genre, Actor, Franchise, Season, Episode, or MediaType. In this example, you should show the customer search results for "batman" in your app.
Once your app handled the directive successfully (or not), your BroadcastReciever class should send a success intent back with a status in the form of a true (for success) or false (for failure) value.
Get started
Learn more about integrating VSK through our the developer documentation here. You can also follow this high-level video tutorial about integrating the VSK into your Fire TV app.
