Step 10: Test Utterances and Observe Logs

It's time to test your skill and observe the directives Alexa sends to your app. You'll view the interactions through the Logcat pane in Android Studio or through Grep commands in a terminal.

• Set Up a Fire TV Device
• Connect to Fire TV and Run the App
• Say a Test Utterance
• Implicit versus Explicit Utterances
• Commands to See Directives in the Logs
• More Detailed Log Walkthrough
• Troubleshooting
• Prepare for Certification: Required Directives You Must Handle
• Submit for Certification and Publishing
• Next Steps: Live TV Integration?

Set Up a Fire TV Device

You need a Fire TV device, such as a Fire TV Stick 4K, associated with your developer account in order to test your VSK integration. The remote control for the Fire TV device needs to have a microphone button. Set up your Fire TV and register it to your developer account.

Connect to Fire TV and Run the App

1. Connect to a Fire TV device. See Connect to Fire TV Through ADB for details on how to connect your computer to a Fire TV through ADB.

2. Open Android Studio, select the app configuration, and then select the Fire TV device (for example, "Amazon AFTMM") to run your app on. ("AFTMM" refers to the Fire TV build model.)

   

3. Click the Run App button to sideload your app onto Fire TV.

   

   While your app builds and runs, click the Logcat tab at the bottom of Android Studio to monitor the log messages.

   Sample App Notes
   
   The sample app's home screen looks like this:
   
   

   Several common videos are integrated into the sample app.

If you run into issues in this step, try the following to troubleshoot:

• If you get an error message (e.g., some entry names collided), go to Build > Rebuild Project to see if it clears up any outdated artifacts, and then run the app again.
• If you get an installation conflict, make sure your Fire TV doesn't have any other apps with this same package name. Uninstall any apps as needed (Settings > Applications > Manage Installed Applications).
• If the app loads a blank screen or has other issues, open Logcat and filter on "Error." If you see an error that says "Invalid API key," check to make sure you're signing your app with the custom firetv signing key you configured earlier.

Say a Test Utterance

With the app running in the foreground of your Fire TV (meaning, it's the active app that you're currently viewing), press the microphone button on your remote control and say, "Alexa, watch Batman" (or any other movie or TV show title in the IMDb catalog).

Implicit versus Explicit Utterances

Before getting into the various test cases and start examining logs, note the different contexts in which you can make requests/utterances:

• Implicit targeting: A voice command that does not specify the content provider or app name, e.g., "Watch Batman." Alexa looks across the entire catalog for matches.
• Explicit targeting: A voice command that specifies the content provider or app name, e.g. "Watch Batman on app name." Alexa looks only in the app's catalog for matches.
• Implicit targeting with app in foreground. If your app is in the foreground (rather than the background), when you say "Watch Batman," Alexa looks for matches within the foregrounded catalog's app (rather than in all catalogs). If the foreground app can handle the directive, then Alexa allows the foreground app to handle it. If not, then Alexa disambiguates by asking, "I can do that on Fire TV or Prime video, which would you like?" Note that making requests with your app in the foreground simulates explicit targeting even when you don't specify your app name in the request.

Note that explicit targeting will only work in your real app after (1) you've completed catalog integration and (2) you've either submitted your app (not necessarily VSK-integrated) into production at some point or into Live App Testing (LAT). (The Amazon services required to support explicit targeting require your app to be in either the prod or LAT state.) If your app isn't in this state, you can simulate explicit targeting by making requests with your app in the foreground.

Commands to See Directives in the Logs

Once your app responds successfully to your test command ("Alexa, watch Batman"), it's time to start looking at the logs. You can monitor logs in two ways:

• Logcat in Android Studio: Use the Logcat pane in Android Studio to filter on a specific word, or
• Grep command in terminal: Open a terminal window and use a Grep filter.

The following table shows how to filter on the logs to verify the results.

(In the Grep commands, the -i ignores the word's casing.)

To view directives received in the Android Studio logs:

1. Open the Logcat pane in Android Studio and, with your app running, filter on this word: AlexaDirectiveReceiver.

2. With your app running in the foreground on Fire TV, say "Watch Batman."

   The logs show the following:

   

   Logcat shows a directive such as the following received:

   Received an Alexa Directive: Alexa.RemoteVideoPlayer#SearchAndPlay with payload version: 3 and payload: {"searchText":{"transcribed":"batman"},"entities":[{"externalIds":{"ENTITY_ID":"0"},"type":"Franchise","uri":"entity://avers/franchise/Batman","value":"Batman"}]}
   

   Let's expand that directive log and payload. Because the utterance used "watch," Alexa sends a SearchAndPlay directive from the RemoteVideoPlayer interface:

   Received an Alexa Directive: Alexa.RemoteVideoPlayer#SearchAndPlay with payload version: 3 and payload:
   
   {
     "searchText": {
       "transcribed": "batman"
     },
     "entities": [
       {
         "externalIds": {
           "ENTITY_ID": "0"
         },
         "type": "Franchise",
         "uri": "entity://avers/franchise/Batman",
         "value": "Batman"
       }
     ]
   }
   

   In this case, because "batman" is a franchise (meaning there are multiple Batman movies), the directive includes "type": "Franchise". See Watch by Franchise for more details, as well as the Franchise List.

More Detailed Log Walkthrough

Here's a more detailed log (with explanatory comments) of what you see in the logs if you filter in Logcat on "AlexaDirectiveReceiver". These logs show the full interaction when a user says "Watch Batman" (which results in a SearchAndPlay directive from the RemoteVideoPlayer interface.) The timestamps and other prefaces for each line were removed for readability here.

// The VSK Agent sends an intent that is handled by the MyStreamz app
AlexaDirectiveReceiver: Handling Intent from VSK Agent: Intent { act=com.amazon.alexa.vsk_app_agent_api.ACTION_ALEXA_DIRECTIVE flg=0x10000010 pkg=com.example.vskfiretv.mystreamz cmp=com.example.vskfiretv.mystreamz/.receiver.AlexaDirectiveReceiver (has extras) }

// The VSK Agent sends the SearchAndPlay directive to the app
AlexaDirectiveReceiver: Received an Alexa Directive: Alexa.RemoteVideoPlayer#SearchAndPlay with payload version: 3 and payload: {"searchText":{"transcribed":"batman"},"entities":[{"externalIds":{"ENTITY_ID":"0"},"type":"Franchise","uri":"entity://avers/franchise/Batman","value":"Batman"}]}

// The app's logic handles the directive by playing a random movie.
// Here is where your app would need to implement custom logic to react to the directive.
AlexaDirectiveReceiver: Handling SearchAndPlay directive...
AlexaDirectiveReceiver: Playing some random Movie Video Two
AlexaDirectiveReceiver: Handling SearchAndPlay directive finished

// The app sends a success message to the VSK agent indicating that the request has been handled

Troubleshooting

If you're experiencing issues receiving directives and want to request that the VSK Agent send your app a test directive, you can do so using the requestTestDirectiveFromVSKAgent() method from the VSK Agent client. See Testing Dynamic Capabilities Integrations (Optional) for details.

Another debugging tool, which is available for all Android-based apps, is Android Debug Bridge (ADB). Type adb help to see a full list of available commands.

Prepare for Certification: Required Directives You Must Handle

As you prepare for certification, test your app against all the utterances related to the directives you support. Go to the VSK Fire TV Certification for a consolidated list of utterances sorted by directive. If desired, you can print this page out and mark the Completed check box to indicate your support for the requirements.

Any utterances that include the label Required for certification must be supported to pass certification. After you submit your app for certification and publishing, a tester on the Appstore ingestion team will test your app against the utterances that are required for Required for certification (modifying the sample requests for titles in your catalog) and check whether the result aligns with the expected response for that utterance. If you app doesn't handle the required utterances appropriately, your app will probably not pass certification. In some cases, you might need to work with your Amazon representative to troubleshoot any issues outside of your control.

Submit for Certification and Publishing

When you're ready to submit your app for certification and publishing, do the following:

1. End any LAT tests. In an earlier step, you submitted your app to Live App Testing (LAT). Cancel the LAT by doing the following:

   1. Log into the developer console and go to Apps & Services > My Apps and click your app.
   2. Click Live App Testing in the left sidebar.
   3. In the Actions column, click the three dot menu and select End Test. Then click OK to confirm the selection.

2. Publish your app. Continue with the usual steps to publish or update your live app:

   • If your app isn't already in the Appstore, see Submitting Apps to the Amazon Appstore.
   • If your app is already in the Appstore, see Update a Published App.

Amazon will test and certify your app to make sure the app-only VSK integration is working as it should. When the evaluation is completed and your app passes certification, your app will be published.

Next Steps: Live TV Integration?

After you've integrated the VSK, what's next? If you have live content in your app, you can integrate with Fire TV's Live tab and Channel Guide. See Introduction to Linear Television to get started.

Last updated: Oct 18, 2023