Fire TVのUIから注目コンテンツへのディープリンク

ディープリンクとは、アプリのホームページではなく、アプリ内の特定のコンテンツへユーザーを直接誘導するリンクです。マーチャンダイジングのコンテキストでは、ディープリンクをたどると、宣伝対象のコンテンツに誘導されます。ここでは、ユーザーが既にアプリをダウンロードしていると仮定しています。ディープリンクを設定するには、目的のコンテンツを指定する、エンコードされたディープリンクインテントを提供する必要があります。その後、このディープリンクインテントをAmazon側でキャンペーンに実装します。

注目コンテンツへのディープリンクについて
前提条件
コンテンツのエンコード済みディープリンクインテントの生成
- 手順1：メディアにディープリンクするadbコマンドを作成する
- 手順2： Android Studioを使用してディープリンクインテントをエンコードする
ディープリンクが破棄される場合の処理
よくある質問（FAQ）

注目コンテンツへのディープリンクについて

ディープリンクは、Fire TV OSから、Fire TV上のアプリに含まれる特定のコンテンツにユーザーを誘導します。注目コンテンツのコンテキストでは、ディープリンクをたどると、宣伝対象のコンテンツに誘導されます。

たとえば、「ACME Media」のマーチャンダイジングプレースメントでサッカーのプレーオフを宣伝する場合、ACMEユーザーがプレーオフのプレースメントをクリックすると、アプリ内の該当するページに直接誘導されます。ユーザーはそこで試合の視聴や録画ができます。

ユーザーがFire TVにアプリをダウンロードしていない場合は、アプリの詳細ページが表示されます。ユーザーはこのページからアプリをダウンロードして、開くことができます。アプリをダウンロードして開くと、キャンペーンで宣伝中のコンテンツに直接移動します。

ディープリンクを使用すると、Fire TVに表示される注目コンテンツへ、ユーザーをいつでも直接誘導できます。これは、キャンペーンに表示されるコンテンツから、アプリ内の同じコンテンツへのシームレスな遷移が可能になるためです。

Fire TVのディープリンクの新機能

以前は、ユーザーがFire TVで注目コンテンツをクリックした場合、アプリをダウンロードしていても、そのアプリの詳細ページが表示されるだけでした。現在では、アプリ内の該当するコンテンツを直接表示できるようになりました。

前提条件

エンコードされたディープリンクインテントを生成するには、Android StudioとADBを使用する必要があります。Android Studioでは、ADBがデフォルトでインストールされます。ADBを初めて使用する場合は、AndroidドキュメントのAndroid Debug Bridge（adb）で詳しい設定方法を確認してください。

コンテンツのエンコード済みディープリンクインテントの生成

シンプルなアプリのコードをカスタマイズすることで、エンコードされたディープリンクインテントを生成する必要があります。ディープリンクインテントのカスタマイズは、adbコマンドで使用されるパラメーターによって異なります。コンテンツへのディープリンクインテントをエンコードするには、以下の2つのセクションに従います。

手順1：メディアにディープリンクするadbコマンドを作成する

メディアのディープリンクのインテント値が既にわかっている場合は、手順2： Android Studioを使用してディープリンクインテントをエンコードするに進んでください。ただし、その場合でも、インテント値がメディアを表しているかどうかをテストするためにadbコマンドを設定する必要があります。これは、送信前にディープリンクインテントをテストする方法がほかにないためです。

メディアのadbコマンドを作成するには、以下の手順を実行します。

ディープリンクインテントを生成するadbコマンドを作成します。たとえば、メディアを再生するadbコマンドは次のようになります。
```
adb shell am start -a android.intent.action.VIEW -n air.ACMEMobilePlayer/.ACMEActivity -d http://app.site.acme.com/amazonfiretv/?channel=acme
```
Androidでは、ディープリンクをさまざまな形式で構造化できますが、各アプリで使用されるディープリンクの形式は、そのアプリにしかわかりません。コマンドでは、さまざまなパラメーターとコンポーネントを使用できます。通常、adbコマンドでは、adb shell am startと次のパラメーターを使用します。
- -a（アクション）：インテントアクションを指定します。
- -n（パッケージ+コンポーネント）：パッケージとコンポーネント名を指定します。
- -d（data_uri）：インテントデータURIを指定します。
adbに渡すパラメーターの詳細については、Androidドキュメントのインテント引数の指定を参照してください。ディープリンクの作成に関する一般的な情報については、アプリコンテンツへのディープリンクの作成を参照してください。
ADBをFire TVに接続し、adbコマンドを実行します（接続方法については、ADBを使用してFire TVに接続する方法を参照してください）。
Fire TVに適切なメディアが表示されていることを確認します（adbコマンドが失敗すると、次のセクションで生成したエンコード済みディープリンクも失敗します）。

手順2： Android Studioを使用してディープリンクインテントをエンコードする

adbコマンド（ディープリンクインテント）をエンコード文字列に変換する必要があります。それには、シンプルなAndroidアプリをダウンロードします。このアプリのクラスには、必要に応じてカスタマイズできるさまざまなメソッドが用意されています。このアプリでは、adbコマンドからパラメーターを取得し、amazonIntentというインテントオブジェクトに格納します。

すべてのadbパラメーターをamazonIntentに追加したら、toURIメソッドを使用して、amazonIntentオブジェクトをエンコードされたURI文字列に変換します。エンコードされたURI文字列には、adbコマンドのすべての情報（アクション、パッケージ、コンポーネント、フラグ、エクストラなど）が含まれています。このAndroidアプリを実行すると、エンコードされたURI文字列がLogcatコンソールに表示されます。

エンコードされたディープリンクインテントをAndroid Studioで生成するには、以下の手順を実行します。

シンプルなAndroidアプリ（toURI）をダウンロードします。ダウンロードが完了したら展開します。
Android Studioを起動し、toURIアプリを開きます（Android Studioでこのアプリを開くと、Android SDKの場所が自動的に更新されます）。

（app/java/com/example/touriにある）MainActivity.javaファイルを開き、コメントの説明に従ってコードをカスタマイズします。カスタマイズするセクションは6つあります。

注：各セクションの詳しいカスタマイズ方法は、toURIアプリのコメントに記載されています。わかりやすいように、以下にも簡単に説明します。以下のコードはtoURIアプリからの抜粋です（Android Manifestファイルを除く）。

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.アプリのASINを指定します（ASINがわからない場合は、アプリの
//Amazonアプリストアページを開きます。ASINは「商品詳細」の下にあります）。
        String asin = "B123ABC456";

//次の行はそのままにします。ここでは新しいインテントオブジェクト
//（amazonIntent）を作成します。adbコマンドのすべてのパラメーターをこのオブジェクトに格納します。

        Intent amazonIntent = new Intent();

//2.アクションを指定します。adbコマンドで-aパラメーターから値を取得し
//以下のメソッドのパラメーターとして挿入します（その値で
//android.intent.action.VIEWを置き換えます）。adbコマンドに-aパラメーターがない場合は、
//既存の値をそのままにします（コメントアウトしないでください）。

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

//3.任意のフラグを指定します。adbコマンドで-fパラメーターから値を取得し
//以下のメソッドのパラメーターとして挿入します（その値で
//Intent.FLAG_ACTIVITY_SINGLE_TOPを置き換えます）。次に、この行のコメントを解除します。adbコマンドにフラグがない場合は
//このセクションをスキップしてください。

        //amazonIntent.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP);

//4.クラスとコンポーネントを指定します。adbコマンドで-nパラメーターの値を取得し、
//それを以下のComponentNameメソッドのパラメーターとして挿入します。
//adbコマンドでは、パッケージ名とコンポーネントがスラッシュで区切られています。
//このパラメーター形式では、次に示すようにパッケージとコンポーネントを
//コンマで区切ります。-nパラメーターがない場合は、このセクションをスキップしてください。

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

//5.追加オプションを指定します。adbコマンドで-eパラメーターから値を取得し、
//以下の.putExtraメソッドのパラメーター（キーと値のペア）
//として挿入します。-eパラメーターがない場合は、このセクションをスキップしてください。

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

//6.データを指定します。adbコマンドで-dパラメーターから値を取得し、
//以下の.Uri.parseメソッドのパラメーターとして挿入します（コンテンツIDを
//URIと見なしています）。 adbコマンドに-dパラメーターがない場合は、このセクションを
//スキップしてください。

        //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());
    }

 //1～6に記載されているカスタマイズが完了したら、（エミュレーターまたは
 //デバイスで）アプリを実行し、Logcatを開いて「amazon」でフィルタリングします。エンコードされた
 //ディープリンクインテントが出力されます。
}

コードのカスタマイズが完了したら、[Run App] ボタンを選択し、任意のデバイス（エミュレーターまたは接続されたFire TVデバイスなど）でアプリを実行します。
Logcatを開き、「amazon」でフィルタリングします。「amazon_intent=:」の後に表示される値を確認します。

「amazon」でフィルタリングして、エンコードされたディープリンクインテントを取得

エンコードされたディープリンクインテントは、次のような文字列になります。
```
amzns://apps/android?asin=B123ABC456#Intent;S.intentToFwd=https%3A%2F%2Fwww.acme.com%2Fsome%2Fshow%2Frrn%3Acontent%3Ashows%3A123456789;end
```
この値をコピーし、Amazonの担当者に送信します。

ディープリンクが破棄される場合の処理

ほとんどの場合、ユーザーがキャンペーンをクリックすると、アプリのメディアが開いて再生が始まります。ただし、ユーザーがアプリを開く前にディープリンクが破棄されるケースや、（何らかの理由で）ディープリンクのメディアを利用できないケースにも対処する必要があります。そのような場合は、代わりにユーザーをホームページに誘導することもできます。

次に示す図は、ディープリンクが破棄される可能性があるシナリオです。

キャンペーンをクリックしたユーザーがアプリをインストールしていない場合は、アプリの詳細ページへ誘導し、アプリのダウンロードを促します。アプリの詳細ページがアクティブである限り、ディープリンクインテントはメモリに格納されたままとなります（これを「ディファードディープリンク」と呼びます）。ただし、ユーザーが詳細ページから移動すると、格納されたインテントデータは削除されます。

たとえば、ユーザーがアプリのインストールを開始したものの、（ダウンロードの完了を待ちきれずに）アプリを開く前に別の場所へ移動したとします。その後、インストールしたアプリに戻って開いた場合、アプリの詳細ページからいったん離れているため、ディープリンクのデータは既に削除されています。このようなときは、代わりにホームページに誘導します。

よくある質問（FAQ）

アプリにディープリンク機能を実装するにはどうすればよいですか？: 詳細については、Androidドキュメントのアプリコンテンツへのディープリンクの作成を参照してください。
アプリがディープリンクに対応しているかどうかを確認するには、どうすればよいですか？: adbコマンド（ディープリンクインテント）を使用してアプリ内のメディアを再生できる場合、そのアプリはディープリンクに対応しています。更新の必要はありません。
ディープリンクがFire TVで機能しているかどうかを確認するには、どうすればよいですか？: 手順1に従ってadbをFire TVに接続し、adbコマンドを実行して、Fire TVに適切なメディアが表示されることを確認します。adbコマンドが正しく動作することがわかったら、手順2に従って、エンコードされたディープリンク文字列を生成します。これでディープリンクが機能するようになります。ディープリンクは、Amazonが内部ツールを使用してテストします。エンコードされたディープリンクインテントをご自身でテストする方法はありません。
ユーザーが既に破棄されているディープリンクをたどろうとした場合、または移動したメディアや存在しないメディアにディープリンクが関連付けられている場合、アプリはどのように動作しますか？: アプリのデフォルトのホームページを表示するなど、適切な方法で対処します。
ディファードディープリンクをサポートしていますか？: はい。ディファードディープリンクは、ユーザーがアプリをダウンロードしていない場合でも、アプリ内の特定の遷移先をキャッシュし、ユーザーが初めてアプリをダウンロードして開いたときに、アプリ内のキャッシュされた遷移先にユーザーを転送するメカニズムです。このドキュメントで言及している「ディープリンク」には、ディープリンクとディファードディープリンクの両方が含まれます。ディファードディープリンクは、ユーザーがアプリの詳細ページから移動することなく、アプリをダウンロードして開いた場合にのみ機能します。