Developer Console
Sign In
Sign In
Developer Console

Deep Linking to Featured Content from the Fire TV UI

Deep linking refers to links that direct users past the homepage of an app to specific content inside the app. In the context of merchandising, deep links take users from the merchandising placement to the exact content promoted in the merchandising, assuming the user has already downloaded your app. To set up deep linking, you must provide an encoded deep link intent that points to your content. Amazon will then implement this deep link intent with your campaign.

About Deep Linking with Featured Content

Deep links take users from the Fire TV OS into a specific destination within an app on Fire TV. Within the context of featured content, deep links take users to the content being promoted.

For example, if a merchandising placement for "ACME Media" promotes a Football Playoff game, any ACME customers who click on the Football Playoff placement will be taken directly to the page for that Football Playoff game within the app, where they can watch the game or record it for future viewing.

If the customer has not previously downloaded your app on their Fire TV, the campaign will take users to your app details page, where the user can choose to download and open your app. After users download and open your app, they will be taken directly to the content promoted in the campaign.

Overall, deep linking gives more immediacy and continuity to the featured content displayed on Fire TV because the deep link provides a seamless transition from the content displayed in the campaign to the destination in the app for that same content.

What's new with deep linking on Fire TV

Previously, when customers clicked on featured content on Fire TV, they were taken only to the detail page for that app, even if they had already downloaded the app. Recent developments now make it possible to deep link to content inside the app.

Prerequisites

You will need to use Android Studio and adb to generate the encoded deep link intent. adb is installed by default with Android Studio. If you're new to adb and need more info on setting it up, see Android Debug Bridge (ADB) in the Android docs.

Generate an Encoded Deep Link Intent for your Content

You need to generate out an encoded deep link intent by customizing some code in a simple app. Your customizations for the deep link intent will depend on the parameters used in your adb command. To generate an encoded deep link intent to your content, follow the two sections below.

Step 1: Create adb Command That Deep Links to your Media

If you already know the deep link intent values for your media, you can proceed directly to the next section, Step 2: Encode your Deep Link Intent Using Android Studio. However, you should still configure an adb command to test that the values surface your media, since there's no other way to test the deep link intent before submitting it.

To create an adb command to your media:

  1. Create an adb command that provides your deep link intent. For example, your adb command to play the media might look like this:

    adb shell am start -a android.intent.action.VIEW -n air.ACMEMobilePlayer/.ACMEActivity -d http://app.site.acme.com/amazonfiretv/?channel=acme

    In Android, deep links can be structured in different ways, and how each app chooses to structure deep links is known only to the app. You might use different parameters and components in your command. Your adb command will typically use adb shell am start and several parameters:

    • -a (action) - specifies the intent action
    • -n (package + component) - specifies the package and component name
    • -d (data_uri) - specifies the intent data URI

    For a description of parameters to pass into adb, see Specification for intent arguments in the Android docs. For more general information about creating deep links, see Create Deep Links to App Content.

  2. Connect adb to Fire TV and run your adb command. (For help connecting, see Connect to Fire TV Through ADB.)
  3. Ensure that the right media appears on your Fire TV. (If the adb command fails, then the encoded deep link that you generate in the next section will also fail.)

You need to convert your adb command (deep link intent) to an encoded string. To do this, you will download a simple Android app. The app has an a class with various methods that you will customize as needed. In the app, you will take the parameters from your adb command and store them in an intent object called amazonIntent.

After adding all your adb parameters into amazonIntent, the toURI method converts this amazonIntent object into an encoded URI string. The encoded URI string contains all the information from your adb command (the action, package, component, flags, extra, etc.). When you run the Android app, the encoded URI string gets printed in the Logcat console.

To generate your encoded deep link intent in Android Studio:

  1. Download this simple Android app: toURI. After downloading it, unzip it.

  2. Open Android Studio and open the toURI app. (When you open the app, Android Studio will automatically update the location of the Android SDK.)

  3. In MainActivity.java file (inside app/java/com/example/touri), customize the code based on the description in the comments. There are six sections to customize.

    package com.example.touri;

import android.content.ComponentName;
import android.content.Intent;
import android.net.Uri;
import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;
import android.util.Log;

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

// 1. Specify the ASIN of your app. (If you don't know your ASIN, go to your app in
// the Amazon Appstore. The ASIN appears under Product details.)
        String asin = "B123ABC456";

// Leave the following line as is. Here you're creating a new intent object called
// amazonIntent where you're storing all the parameters from your adb command.

        Intent amazonIntent = new Intent();

// 2. Specify the action. In your adb command, grab the value from your -a parameter
// and insert it as the parameter in the method below, replacing
// android.intent.action.VIEW. If you don't have an -a parameter in your adb command,
// leave the existing value as is (don't comment it out).

        amazonIntent.setAction("android.intent.action.VIEW");

// 3. Specify any flags. In your adb command, grab the value from your -f parameter
// and insert it as the parameter in the method below, replacing
// Intent.FLAG_ACTIVITY_SINGLE_TOP. Then uncomment the line. If you don't have any
// flags in your adb command, skip this section.

        //amazonIntent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);

// 4. Specify the class and component. In your adb command, grab the value from your
// -n parameter and insert it as the parameter for the ComponentName method below. In
// your adb command, a slash separates the package name from the component. In the
// parameter format here, separate the package from the component with a comma
// following the format shown. If you don't have an -n parameter, skip this section.

        //amazonIntent.setComponent(new ComponentName("tv.acme.android","tv.acme.android.leanback.controller.LeanbackSplashOnboardActivity"));

// 5. Specify any extras. In your adb command, grab the value from your -e parameter
// and insert it as the parameter for the .putExtra method below, following the
// key-value pair format shown. If you don't have an -e parameter, skip this section.

        //amazonIntent.putExtra("acme_id", 12345);

// 6. Specify the data. In your adb command, grab the value from your -d parameter and
// insert it as the parameter for the .Uri.parse method below. (This assumes your
// content ID is a URI.) If you don't have a -d parameter in your adb command, skip
// this section.

        //amazonIntent.setData(Uri.parse("https://www.acme.com/some/show/rrn:content:shows:123456789"));

        Intent DeepLinkIntent = new Intent(Intent.ACTION_VIEW, android.net.Uri.parse("amzns://apps/android?asin=" + asin));
        DeepLinkIntent.putExtra("intentToFwd", amazonIntent.toURI());
        Log.i("amazon_intent=", DeepLinkIntent.toURI());
    }

 // After completing any customizations listed in 1 through 6, run your app (on any
 // emulator or device) // and open Logcat to filter on "amazon". Your encoded deep
 // link intent will be printed there.
}
  4. After you finish customizing the code, click the Run App button Run 'app' and run the application on any device (any emulator or connected Fire TV device, etc.).

  5. Open Logcat and filter on the word "amazon". The value appears after "amazon_intent=:".

    Filtering for amazon to get the encoded deep link intent
    Filtering for amazon to get the encoded deep link intent

    The value will be an encoded string such as this:

    amzns://apps/android?asin=B123ABC456#Intent;S.intentToFwd=https%3A%2F%2Fwww.acme.com%2Fsome%2Fshow%2Frrn%3Acontent%3Ashows%3A123456789;end
  6. Copy the value and send this to your Amazon representative.

In most cases, users will click the campaign and the media from your app will open and play. However, you should handle scenarios where the deep link might be destroyed before the user opens the app, or cases where (for whatever reason) the media in the deep link isn't available. In those cases, you might decide to take users to your homepage instead.

The following diagram shows scenarios where the deep link might be destroyed.

Workflow for deep links
Workflow for deep links

After clicking the campaign, if user does not have the app, the user is taken to the app details page with the option to download the app. The deep link intent will be stored in memory as long as the app details page remains active. (This is called "deferred deep linking.") However, the stored intent data will be removed if the user navigates away from the details page.

For example, suppose the user installs the app, but before the user opens the app, the user navigates elsewhere (perhaps the user is impatient in waiting for the download to finish). When the user returns and opens the app, the deep link content will have been removed because the user navigated away from the app details page. In these cases, take the user to your homepage instead.

FAQ

How do I implement deep-link functionality in my app?
See Create Deep Links to App Content in the Android docs for more details.
How can I tell if my app is ready to deep link?
If you can play the media in your app through the adb command (deep link intent), then your app is ready and doesn't need to be updated.
How do I know if my deep link works on Fire TV?
You can connect adb to Fire TV and run your adb command to ensure that the right media appears on your Fire TV, as per Step 1. If your adb command works correctly, and you followed the instructions on generating the encoded deep link string, it should work. Amazon will also test the deep link using an internal tool. There's no way for you to test the encoded deep link intent yourself.
If a user tries to follow a deep link that has been destroyed, or if the deep link points to media that has been moved or is missing, how should the app behave?
The link should fail gracefully, such as leading to the default homepage for the app.
Do you support deferred deep linking?
Yes. Deferred deep linking is the mechanism that caches a specific destination within an app, even if the user has not downloaded an app, and transfers the user to that specific, cached destination within the app the first time the user downloads and opens the app. In this documentation, all references to "deep linking" include both deep linking and deferred deep linking. Deferred deep linking works only if users do not navigate away from the app detail page before they finish downloading and opening the app.