Developer Console

Step 8: React to Directives (VSK Fire TV)

After you add a BroadcastReceiver in your manifest, Fire TV will send any intents with Alexa directives to the BroadcastReceiver class you specify, e.g., AlexaDirectiveReceiver. This BroadcastReceiver class is where you accept and handle the directives Alexa sends to your app. You'll need to develop your own handling logic in this class.

Sample App Notes

The sample app already reacts to directives, so you don't need to do any coding in this step. You can view how the sample app handles directives in the AlexaDirectiveReceiver class (inside java/com/example/vskfiretv/company/receiver). Expand the "How the Sample App Handles Directives" button section near the bottom of this topic for an explanation of the sample app's handling logic.

VSK Directives

VSK directives are communicated to your app through the VSK Agent when a user makes a voice request through Alexa. More detail about the directives are described in the API Reference.

Once you receive the directive in your BroadcastReceiver, you need to fulfill the request of the directive in your app yourself. A commonly designed model-view-viewmodel (MVVM) application usually makes this fairly straightforward as most apps have Master View Model that already routes remote clicks and search queries around the application. Passing the pertinent string from the BroadcastReceiver to your View Model is usually all that is needed to execute a VSK directive in your app.

As an example, when the user says, "Find comedy movies," you might receive a SearchAndDisplayResults directive for MediaType: Movie and Genre: Comedies. If your app supports search, you already have a mechanism for the user to input text into an input field with the remote and search what they type. You can use the same search query mechanism with the VSK to execute against "comedy movies" as parsed from the directive.

Reacting to Directives

The directives Alexa sends depends on the capabilities you declare. Customize your BroadcastReceiver class to handle the directives within your app (as described in Step 7: Add a BroadcastReceiver). More specifically:

  • Add logic to parse the directive payload (which is present in intents received by these directives) and execute the requested behavior in your app.
  • Respond to the VSK Agent with the directive to indicate whether it was handled successfully or not. You include this status via the PendingIntent included in the broadcast intent. The status is a Boolean, with either a true (for success) or false (for failure) value. Sample response code is shown in the Add a BroadcastReceiver Java Class in Step 7.

Directives That Are Required for Certification

Alexa can send directives for a lot of different requests. Do you have to handle them all? If your app doesn't handle certain directives, will your app fail certification? In the list of utterances for each directive, if support for an utterance is required, the words "Required for certification" appear below this utterance.

Required utterances include searches for titles, actors, genres, franchises, as well as transport-control utterances. If an utterance is marked as required, but your app doesn't support the capability, your app won't fail certification and you can disregard that requirement. For optional directives such as ChangeChannel, the required directives are only requirements if you choose to handle that directive.

API Reference

The expected logic for implementing and handling each of the above directives is described in the API reference documentation. Alexa expects a specific response and action for each incoming directive. See the following for more details:

If you're implementing some of other interfaces (not recommended), see the following:

Utterances Reference

See the Utterances Reference for a detailed list of the various utterances that Fire TV devices support, including each phrase by locale as well. You can view the utterances for the RemoteVideoPlayer here:

Utterances for other interfaces are here:

Sample App Notes

For a detailed explanation about how the sample app handles directives, expand the following section.

Next Steps

Go to the next step: Step 9: Sign Your App and Configure a Security Profile.