Developer Console
Sign In
Sign In
Developer Console

Step 2: Verify Deep Links from the Catalog

 Implement Universal Search and Browse

STEP 1:
Integrate Your App with the Launcher
→
STEP 2:
Verify Deep Links from the Catalog

Before submitting your app to the Amazon Appstore, validate your integration by running through the test cases listed here. Successfully validating the correct behavior will help facilitate your app's acceptance to the Appstore. Depending on the state (published or unpublished) and conditions of your app (login required or not, free trial or not), you will only need to perform the steps that apply to your app.

Initiate Comrade with adb to see intents sent

To see the intents your app sends, connect to your Fire TV device using adb and initiate Comrade. Comrade is the name of the Fire TV API that manages content with the launcher.

  1. First, uninstall your app.

    To uninstall your app, go to Settings > Applications > Manage Installed Applications. Select your app, and then click Uninstall twice.

  2. Connect to Fire TV device via adb. For example:

    adb connect 10.49.172.33:5555

    You can find your network address at Settings > My Fire TV > About > Network. (Some models say "Device" instead of "My Fire TV.")

  3. Install your app using adb. For example:

    adb install <path-to-apk-file>

    See Install and Run Your App for more details.

  4. Clear logcat:

    adb logcat -c

  5. Run the following command, depending on your Fire TV device OS version:

    adb logcat | grep FTVCS:ComradeActionHandler

  6. Leave the terminal open so you can monitor the Intents that are sent. Then initiate the actions shown in the next section, Action initiated and intents sent, and observe the responses. A later section, Sample output from the adb commands, shows sample output that you should see in your terminal.

Action initiated and intents sent

This section shows the actions initiated and subsequent Intents that should be sent as a result.

Action Initiated Intents Sent
At first launch, such as any of the following:
  • app launch after install ...
  • app launch after device restart ...
  • app launch after force stop ...

... the Sign-in intent should be sent by default.

... the Playback intent should only be sent at this time if any of the following is true:

  • Viewing all content does not require sign-in (that is, all your content is free to watch without requiring an account, even if account creation is free)
  • Your app uses SSO, and there is a valid SSO token for your app
  • Your app uses its own type of automatic verification and validates the user has access
After successfully signing in … … the Playback intent should be sent
At sign out or log out … … the Sign-in intent should be sent
If your app uses single-sign-on (SSO) and your app is in the background … … when your app resumes and you determine there is a valid SSO token onResume, the Playback intent should be sent. (Note: To move your app to the background, launch your app, then press Home on your remote.)

Sample output from the adb commands

This section shows sample intent outputs that should appear in your terminal, with the key information highlighted. The highlighted values indicate which intent was received from your app:

  • SIGN_IN: Sign-in intent
  • PLAY: Playback intent
  • PARTNER123: Partner's catalog name

Sign-in intent output samples

When receiving a sign-in intent, you will see outputs such as the following:

06-11 16:09:57.448  4347 16145 I FTVCS:ComradeActionHandler: Received capability: SIGN_IN
for partner: PARTNER123 06-11 16:09:57.450  4347 16145 I FTVCS:ComradeActionHandler: Processing
capabilities Capabilities{mPartnerId='PARTNER123', mPackageName='com.yourpackagename.firetv',
mComradeApiVersion=V1, mSubscriptionIds=[],
mCapabilities={SIGN_IN=Capabilities{mCapabilityType=SIGN_IN,
mIntentPackageName='com.yourpackagename.firetv',
mIntentAction='android.intent.action.VIEW',
mIntentClassName='com.partner.android.IntegrationActivity',
mIntentDataExtraName='null', mIntentFlags=-1}}}

The above code uses generic values. You will see your app's own package name, classes, and extras.

Playback intent output samples

When receiving a Playback intent, you will see outputs such as the following:

06-11 16:09:57.379  4347 16145 I FTVCS:ComradeActionHandler: Received capability: PLAY for
partner: PARTNER123 06-11 16:09:57.380  4347 16145 I FTVCS:ComradeActionHandler: Processing
capabilities Capabilities{mPartnerId='PARTNER123', mPackageName='com.yourpackagename.firetv',
mComradeApiVersion=V1, mSubscriptionIds=[],
mCapabilities={PLAY=Capabilities{mCapabilityType=PLAY,
mIntentPackageName='com.yourpackagename.firetv',
mIntentAction='com.yourpackagename.amazon.catalog.ON_MESSAGE',
mIntentClassName='com.yourpackagename.MainActivity', mIntentDataExtraName='null',
mIntentFlags=268435456}}}

The above code uses generic values. You will see your app's own package name, classes, and extras.

In addition to ensuring the right Intents are sent, you should also test the deep link behavior. More specifically, make sure that playback of content selected by a user opens the app and launches directly into video playback (if the app sent the Playback intent) or launches to the sign-in or sign-up screen within their app (if the app sent the Sign-in intent).

Two types of user states should be tested for each deep link scenario: unauthenticated and authenticated users. To test out the deep links, you search for media from your app using Fire TV's universal search, and then select to watch the result in your app. The following table shows the expected conditions and results.

Conditions Result
Unauthenticated state: Your app requires authentication to view content, but the user has not yet signed in. The deep link should take you to the authentication or sign-up screen. After successful authentication, the video should start to play.
Authenticated state: Your app requires authentication to view content, and the user is signed in successfully. Alternatively, all the content is free to watch, even without account creation. The deep link should start playback of video. It should not go to a video detail page.

Test the following deep-link scenarios:

Deep links from a cold start

A "cold start" refers to the first launch of app after it is installed or after force-stopping the app. Deep-link behavior differs if your app must cold start versus if your app is already in the background.

 

To test deep links in an authenticated state from a cold start:

  1. Launch your app.
  2. Sign in to your app.
  3. Press the Home button on the remote.
  4. Force stop the app. Go to Settings > Applications > Manage Installed Applications > [your app] > Force stop.
  5. Use Fire TV's universal search to search for your app's media and then select it. The media detail page shows a Watch Now with <your app> button.
  6. Click Watch Now with <your app> and the media should open in your app.

The deep link should start playback of video. It should not go to a video detail page.

 

To test deep links in an unauthenticated state from a cold start:

  1. Launch your app.
  2. If necessary, sign out of your app.
  3. Press the Home button on the remote.
  4. Force stop the app. Go to Settings > Applications > Manage Installed Applications > [your app] > Force stop.
  5. Use Fire TV's universal search to search for your app's media and then select it. On the media detail page, there might be various subscription options. Your app could be listed under More Ways to Watch. For more information on how this is determined, see The Buy Box.
  6. Click your app to launch it. Your app's sign-in or sign-up screen should appear.

The deep link should take you to the authentication or sign up screen. After successful authentication, the video should start to play.

Deep links with app in background

 

To test deep links in an authenticated stage while your app is in the background:

  1. Launch your app.
  2. Sign in to your app.
  3. Press the Home button on the remote.
  4. Use Fire TV's universal search to search for your app's media and then select it. The media detail page shows a Watch Now with <your app> button.
  5. Click Watch Now with <your app> and the media should open in your app.

The deep link should start playback of video. It should not go to a video detail page.

 

To test deep links in an unauthenticated stage while your app is in the background:

  1. Launch your app.
  2. If necessary, sign out of your app.
  3. Press the Home button on the remote.
  4. Use Fire TV's universal search to search for your app's media and then select it. On the media detail page, there might be various ways to watch your content. Your app might be listed under More Ways to Watch. For more information on how this is determined, see The Buy Box.
  5. Click your app to launch it. Your app's sign-in or sign-up screen should appear.

The deep link should take you to the authentication or sign up screen. After successful authentication, the video should start to play.

Deep links with a video playing

 

To test deep links in an authenticated state while a video is playing:

  1. Launch your app.
  2. Sign in to your app.
  3. Start watching a video in your app.
  4. While watching a video, press the Alexa button on the remote and perform a verbless voice search for content. For example, when searching for Friends, press Alexa and utter "Friends".
  5. Universal search should display the content and your app should stop audio and video playback. Select the content.

The content should autoplay. It should not go to a video detail page.

Test case: Back button returns user to search results

This test case will check for proper behavior with the Back button.

  1. From the Fire TV home screen, search for media from your app.
  2. Select to play the content with your app.
  3. Press the Back button. Pressing the Back button should eventually take you back to the search results.

Test case: sending an invalid content ID

Another test case that you should run is sending an invalid content ID to your app to make sure that your app handles this condition gracefully. If your app does not handle this condition gracefully, re-visit your error handling code and make changes as appropriate.

To test sending an invalid content ID to your app:

  1. Download or sideload your app to your Fire TV device.
  2. Sign in and/or activate a subscription to your app, if necessary.
  3. Use either the Test App (see Test Fire TV Launcher Integration with the Integration Test App) or adb commands (see Test Launcher Integration with ADB) to send an invalid ID to your app.
  4. Send a valid ID first to make sure the content launches properly.
  5. Test the following invalid ID conditions:
    • Send an invalid ID using numerals.
    • Send an invalid ID using alphabetical characters.
    • Send an invalid ID using a mix of numbers and letters.
  6. Verify that when sending invalid IDs, your app handles the intent gracefully.

The app should launch and leave the user on the main screen within your app. Alternatively, your app should provide appropriate messaging, such as "Sorry, the content you select is no longer available." If the user is not taken to the main screen within your app, or no messaging appears, modify your error handling code to do so.

Additional testing

You can optionally perform additional testing with your catalog content by following these two topics:

Last updated: Sep 27, 2024