Developer Console
Sign In
Sign In
Developer Console

Known Limitations for App-only Integrations

The following are known limitations or other issues related to app-only integrations.

Supported Fire TV Devices

You need Version 631098910 or later on your Fire TV device before the app-only integration becomes available for your device. To check if you have the right version:

  1. Connect to your Fire TV through ADB
  2. Run this adb command:
adb shell dumpsys package com.amazon.vizzini | grep versionCode

The response will be something like this:

versionCode=631098910 minSdk=22 targetSdk=28

The versionCode needs to be 631098910 or later. Alternatively, press your microphone button and say a voice command. If the voice chrome (Alexa's blue bar) appears at the bottom of the screen, you have the new build. If it appears at the top, you don't have the new build.

To check your Fire TV build, go to Settings > About. Click either Device & Software or My Fire TV (the menu name differs by device). Then click your Fire TV device and look for the Fire TV Home Version. If you don't see Build 631098910 or later, click Check for updates and get the latest build available.

If you don't want to wait until the rollout dates, you can send your Device Serial Number (DSN) along with your Customer ID (CID) to your Amazon representative to have your device manually added to the software rollout. To retrieve your DSN and CID:

  1. DSN: On your Fire TV, go to Settings > Device & Software (or My Fire TV) > About.
  2. CID: First, sign in to the developer portal; then once signed in, go to https://developer.amazon.com/mycid.html.

Explicit Targeting with the Sample App and other Pre-release Apps

Explicit targeting refers to including the app name in the request, such as "Alexa, watch Interstellar on App Name" rather than just "Alexa, watch Interstellar." Note the following:

  • Explicit targeting won't work in the sample app.
  • Explicit targeting will only work in your real app after (1) you've completed catalog integration and (2) you've either submitted your app into either Live App Testing (LAT) or production. The Amazon services that required to support explicit targeting require your app to be in either the LAT or prod state.

If you do experience issues with explicit targeting, there isn't much that you, as a partner, can do to troubleshoot. Instead, you'll need to raise the issue with your Amazon representative, and Amazon teams will then need to diagnose and troubleshoot the explicit targeting issues using internal tools.

Support for App Name Aliases in Launch Utterances

Apps can be launched with different app names. For example, suppose the app was named "Sports Streamz Now." Users might be able to open the app by saying "Open Sports Streamz," or "Open Streamz Now," or maybe even "Open Streamz." These alternative app names are all recognized aliases. With cloudside integrations, you could specify these aliases in the video skill configuration in the Alexa console. However, app-only integrations don't require you to create a video skill in the Alexa console. (The skill is automatically created for you on the backend, so it's invisible to you.) But as a result, there isn't a place for you to specify aliases to launch your app. Until there's a way to specify aliases, you will need to reach out to your Amazon representative with this request. The VSK team will then create the aliases you need for your app manually.

Support for Web Apps (wrapped webapps)

App-only integrations are designed for native Android projects. If you have an HTML5 Web App, app-only integrations aren't supported. However, if you have a hybrid app (web app wrapped with native Android through wrappers such as Cordova), this approach is supported. However, exactly how you manage the communication between the native layer and the Amazon Web View (AWV) might need to be something you figure out on your own. The VSK team has not tested app-only integrations on hybrid apps. You will need to create a BroadcastReciever that can handle intents, get the directive payloads from intents through your BroadcastReceiver, and then apply handling logic in your app.

The only recommended VSK interface with app-only integrations is RemoteVideoPlayer, specifically the SearchAndPlay and SearchAndDisplayResults directives. For the others, here's what's recommended:

It might seem odd that so many VSK interfaces aren't recommended for Fire TV integrations. Why develop them if they aren't used? Remember that the Video Skills Kit (VSK) isn't used only for Fire TV apps. The same interfaces are used for other devices as well — Echo Show, and third-party devices such as set-top boxes, gaming consoles, or other living room entertainment devices. In these other contexts, some of these interfaces will be more appropriate.

How Alexa Reads Your Catalog

When you declare your app's RemoteVideoPlayer capabilities, you're required to list your partner ID in the catalogs object:

"catalogs": [
  {
    "type": "VIDEO_INGESTION_IDENTIFIER",
    "sourceId": "<INSERT PARTNER ID>"
  }]

However, currently Amazon isn't using this value to retrieve your catalog. Currently, Alexa gets information from your catalog through a backend mapping of your app's ASIN, title, and partner ID. The plan is to use the catalogs object in the future.

Last updated: Jul 27, 2021