DIALの統合

Amazon Fire TVデバイスは、Whisperplayサービスを介してDIAL（Discovery-and-Launch）プロトコルをサポートします。

DIALについて
DIALの実装
Fire TV対応（ファーストスクリーン）アプリの変更
セカンドスクリーンアプリの変更
バージョン履歴

DIALについて

DIAL（Discovery-and-Launch）プロトコル（英語のみ）は、別のデバイスからセカンドスクリーンアプリを使用してFire TV対応アプリを検出し起動できるようにするオープンプロトコルです。これを使用するには、Fire TVとセカンドスクリーンデバイスが同じネットワークに存在する必要があります。

DIALは、ビットストリーミングや画面ミラーリングの機能を提供するAPIではありません。セカンドスクリーンデバイスのアプリがFire TVで（オプションのペイロードを使用して）アプリを見つけて起動できるようにするものです。通常は、セカンドスクリーンアプリ（起動メッセージの送信側）と、対応するファーストスクリーンアプリであるFire TV対応アプリ（メッセージの受信側）の両方を作成して管理・実装します。

オープンDIALプロトコルの詳細と、アプリをDIALサービスに登録する方法の詳細については、DIALのウェブサイト（英語のみ）を参照してください。

DIALの実装

最もシンプルなケース（起動のみの場合）では、DIALを使用するためにAmazon Fire TV対応アプリのコードを変更する必要はありません。ただし、アプリのマニフェストとリソースに変更を加えて、DIALをサポートしていることを示し、起動インテントを受信できるようにする必要があります。以下の図は、DIAL実装の中核となる起動のみのやり取りを例示しています。

ただし、ほとんどのケースでは、DIALの起動パラメーター（ディープリンクなど）を処理したり、DIALサーバーのadditionalDataUrlにフィードバックを送信したりするために、ファーストスクリーン（Fire TV対応）アプリのコードにも変更が必要になります。

一般的に、DIALの大部分の機能を活用して最適なユーザーエクスペリエンスを提供するには、次の5つの手順を実行する必要があります。

Fire TV対応アプリをDIALレジストリに登録します。詳細については、About the Registry（英語のみ）を参照してください。
Fire TV対応アプリで、DIALをサポートするようにAndroidマニフェストを変更します。詳細については、Androidマニフェストを変更するを参照してください。
ファーストスクリーンアプリであるFire TV対応アプリで、whisperplay.xmlファイルをアプリのリソースに追加します。詳細については、whisperplay.xmlファイルを追加するを参照してください。
ファーストスクリーンアプリであるFire TV対応アプリのコード内で、起動インテントとエクストラを処理します。この手順は、セカンドスクリーンアプリがDIAL起動リクエストでペイロードを送信する場合や、DIALサーバーを介してFire TV対応アプリから追加データを受信する場合にのみ必要です。詳細については、起動インテントとadditionalDataUrlを処理するを参照してください。
Fire TVでアプリを見つけて起動するために、セカンドスクリーンアプリにDIALプロトコルを実装します。詳細については、DIALのウェブサイト、特にDetails for Developers（英語のみ）を参照してください。セカンドスクリーンアプリの変更については後述します。

Fire TV対応（ファーストスクリーン）アプリの変更

Fire TV対応アプリには、以下に示す変更を加える必要があります。

手順A： Androidマニフェストを変更する

DIALをサポートするには、Androidマニフェスト（AndroidManifest.xml）に次の2つの変更を加えます。

DIALをサポートしていることを示す<meta-data>要素を<application>に追加します。
起動インテントにDEFAULTカテゴリーを追加します。

マニフェストの<application>部分に、次の<meta-data>要素を追加します。

<application ... >
    <meta-data android:name="whisperplay"  android:resource="@xml/whisperplay"/>
    ...
</application>

次に、DEFAULTインテントカテゴリー（以下のXMLを参照）を、プライマリ（メイン）アクティビティの<intent-filter>要素に追加します。次のセクションで説明するように、DIALのカスタム起動アクションを独自に定義して呼び出しを行うこともできます。

    <activity android:name=".MainActivity"
              android:label="@string/title_activity_main" >
        ...
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER"/>
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>

手順B： `whisperplay.xml`ファイルを追加する

whisperplay.xmlというファイルをアプリのres/xml/ディレクトリにあるリソースに追加します。

重要： DIAL 2.2.1では、CORS認証モデルにいくつかの機能強化が行われています。そのため、whisperplay.xmlファイルでは、以下のコードに示すように、新しい<authorizedOrigins>フィールドに移行することが必須となります。以前の<authorizedDomain>メカニズムとは形式が異なるため、エントリの確認と更新が必要になる可能性があります。

<?xml version="1.0" encoding="utf-8"?>
<whisperplay>
  <dial>
    <application>
    
      <!-- DIALレジストリに登録されているDIALアプリの名前 -->
      <dialid>YourDialAppName</dialid>
      
      <!-- 許可されるクライアントオリジンのコレクション -->
      <authorizedOrigins>
        <origin>https://www.example.com</origin>
        <origin>https://*.test.com</origin>
        <origin>package:com.example.dialapp</origin>
      </authorizedOrigins>
                 
      <!-- アプリのアクティビティ開始時に使用するオプションのインテントアクション -->
      <!-- デフォルトでは、メインのランチャーアクティビティの解決を試みます -->
      <startAction>android.intent.action.MAIN</startAction>
      
      <!-- セカンドスクリーンアプリからDELETEコマンドが送信されたときに使用する
           オプションのインテントアクション（アクティビティを停止する前に送信されます）-->
      <!-- デフォルトでは、DELETE時に追加のインテントは送信されません -->
      <stopAction>YourDeleteAction</stopAction>
    
    </application>
  </dial>
</whisperplay>

<authorizedOrigins>によるCORSのサポート

CORS認証とクライアントオリジンに関する追加要件の詳細については、DIAL仕様v2.2.1のセクション6.6（英語のみ）を参照してください。Amazonの実装では、ファーストスクリーンアプリのwhisperplay.xmlファイル内で、許可されるCORSオリジンのコレクションを指定する必要があります（上記の例を参照）。この形式では、0文字以上の文字列に一致する「*」文字を使用したワイルドカード一致が許可されています。特定の安全でないURIスキーム（file:、http:、ftp:など）は、許可リストへの登録の有無を問わず、明示的に禁止されています。

許可されるオリジンを指定する場合は、過度に許容しないよう注意してください。たとえば、https://test.amazon.comとhttps://amazon.comの両方を許可する場合、許可されるオリジンを*amazon.comとして指定することは避けてください。これは過度な許容であり、予期しないオリジン（https://evilamazon.comなど）が誤って許可されてしまう恐れがあります。このような場合は、代わりにコレクションを以下のように定義することで、所有するドメインに基づくオリジンだけが確実に許可されるようにすることができます。

<authorizedOrigins>
  <origin>https://*.amazon.com</origin>
  <origin>https://amazon.com</origin>
</authorizedOrigins>

重要： 強化されたセキュリティを最大限に活用してユーザーに提供できるよう、DIALアプリにはファーストスクリーン（<authorizedOrigins>）とセカンドスクリーン（ORIGINヘッダー）の両方を追加することを強くお勧めします。

手順C：起動インテントと`additionalDataUrl`を処理する

DIALペイロード（DIAL起動リクエストを介してアプリに渡される情報）を受信するようにアプリが設定されていると、このペイロードは、com.amazon.extra.DIAL_PARAMというキーで文字列インテントエクストラとして送信されます。オプションで追加情報をPOSTするためにファーストスクリーンアプリによって使用されるadditionalDataUrlは、com.amazon.extra.DIAL_ADDITIONAL_DATA_URLというキーで別の文字列インテントエクストラとして送信されます。additionalDataUrlの想定される形式はhttp://127.0.0.1:8009/apps/<YourDialAppName>/dial_dataで、このURLにファーストスクリーンアプリからデータがPOSTされます。

（オプション）追加データのPOST

重要：Android API 28（Fire OS 7）以降では、OSによって追加のクリアテキスト保護が適用されるため、ファーストスクリーンアプリからadditionalDataUrlにデータをPOSTする際に問題が発生する可能性があります。そのため、オプションについてhttps://developer.android.com/training/articles/security-config#CleartextTrafficPermittedで確認することをお勧めします。

ごく基本的な双方向通信や、ファーストスクリーンアプリからセカンドスクリーンアプリへのシンプルなフィードバックメカニズムを有効にする場合は、DIALのadditionalDataUrlフィールドを使用できます。この一般的なユースケースとしては、セッショントークンなどの情報をファーストスクリーンアプリの状態に関連付けて共有するケースが挙げられます。これは、ファーストスクリーンアプリからセカンドスクリーンアプリに提供されるXMLドキュメントとして扱うことができ、Fire TVが再起動されるまで保持されます。Fire TV対応アプリからadditionalDataUrlへのPOSTが正常に実行されるようにするには、対応するオリジンがwhisperplay.xml内の<authorizedOrigins>コレクションに登録されている必要があります。

ファーストスクリーンアプリとセカンドスクリーンアプリの両方の追加データメカニズムで想定および提供される具体的な形式については、DIAL仕様v2.2.1のセクション6.3（英語のみ）を参照してください。

セカンドスクリーンアプリの変更

セカンドスクリーンアプリには、以下に示す変更を加える必要があります。

手順A： DIAL対応デバイス検出サービスを実装する

セカンドスクリーンアプリ（DIALクライアント）に、DIALプロトコルのクライアント仕様を実装します。DIALの検出は、UPnP/SSDPの仕様に基づいて構築されています。バックグラウンドアクティビティまたはスレッドで、検索ターゲットを「urn:dial-multiscreen-org:service:dial:1」と指定して、UDP M-SEARCHリクエストを送信します。

M-SEARCHリクエストに対し、Fire TVから、一意のサービス名（USN）、デバイス情報を取得する場所／URL、検索ターゲットを含むレスポンスが返されます。このレスポンスには、追加のWAKEUPヘッダーが含まれる場合もあります。これは、マジックパケットを使用してサスペンドモードからウェイクアップできる機能がTVに備わっていることを示すものです（詳細については、DIAL仕様v2.2.1のセクション7（英語のみ）を参照してください）。デバイスから複数のM-SEARCHレスポンスを受信することもあるため、USNに基づいて一意のデバイスを抽出する必要があります。

以下は、リクエストとレスポンスの例です。

M-SEARCHリクエストの例：

M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: "ssdp:discover"
MX: 10
ST: urn:dial-multiscreen-org:service:dial:1
USER-AGENT: OS/version product/version

M-SEARCHレスポンスの例：

HTTP/1.1 200 OK
    USN: uuid:7b077d4c-a222-5b72-0000-0000182185c7::urn:dial-multiscreen-org:service:dial:1
    CACHE-CONTROL: max-age=1800
    EXT:
    ST: urn:dial-multiscreen-org:service:dial:1
    LOCATION: http://192.168.1.141:60000/upnp/dev/7b077d4c-a222-5b72-0000-0000182185c7/desc
    SERVER: Linux/4.4.120 UPnP/1.0 Cling/2.0

次に、デバイスの詳細情報を取得するために、M-SEARCHレスポンスに記載されているデバイス情報のURLを使用してHTTPリクエストを送信します。レスポンスのヘッダーには、Application-URLという重要な属性が含まれます。これは、DIAL RESTサービスと呼ばれます。このApplication-URLは、後でデバイス上のアプリとのやり取りに使用されます。レスポンス本文から、デバイスの通称、モデル名、製造元を抽出して格納し、これらの値をユーザーに表示すると便利です。

M-SEARCHリクエストとデバイス情報リクエストの処理が完了したら、検出されたデバイスのリストをUIに表示できます。

手順B：アプリのステータスを取得する

デバイスでアプリを起動する前に、デバイスでのアプリの状態を知っておく（さらに必要に応じてadditionalDataを読み取り、キャッシュされた情報をファーストスクリーンアプリから読み込んでおく）と便利です。アプリの状態を取得するには、アプリを起動するデバイスをユーザーが選択したら、アプリ名をリソース名として指定して、HTTP GETリクエストをDIAL RESTサービスに送信します。リクエスト内のアプリ名は、DIALレジストリに登録（かつwhisperplay.xmlファイルで指定）されている名前と一致する必要があります。

アプリがインストールされていない場合や、アプリ名が認識されない場合は、HTTP 404エラーが返されます。ファーストスクリーンデバイスにAmazonアプリストアからアプリをインストールするオプションを、セカンドスクリーンデバイス上でユーザーに提示できますが、この機能はDIALプロトコルの範囲外です。

HTTPリクエストが成功すると、DIALサーバーはHTTP 200 OKレスポンスで応答します。レスポンス本文には、アプリの状態を伝える属性（hidden、stopped、running、installable）が含まれています（ただし、installableとhiddenは現在Fire TVのDIALサーバーではサポートされていません）。また、以前ファーストスクリーンアプリからadditionalDataUrlにPOSTされていたXML形式のadditionalDataも含まれています。

手順C：アプリを起動する

次に、アプリ名をリソース名として指定し、起動パラメーターとしてアプリに送信するオプションのペイロードをリクエスト本文に記述して、HTTP POSTリクエストをDIAL RESTサービスに送信すれば、ファーストスクリーンアプリを起動できます。一般的なユースケースとしては、アプリ内で再生するビデオコンテンツや音楽コンテンツへのリンクが挙げられます。DIALサーバーは、指定された起動インテントを使用してアプリを起動し、モバイルアプリによって送信されたペイロードをcom.amazon.extra.DIAL_PARAMインテントエクストラに追加します。セカンドスクリーンアプリでファーストスクリーンアプリから追加データを受信する場合は、DIALプロトコルで指定されたリクエストパラメーターのadditionalDataUrlが、com.amazon.extra.DIAL_ADDITIONAL_DATA_URLインテントでファーストスクリーンアプリに送信されます（手順C：起動インテントとadditionalDataUrlを処理するを参照）。

ファーストスクリーンアプリは、セカンドスクリーンアプリから送信されたペイロードに応答してアクションを処理します。ファーストスクリーンのFire TV対応アプリからPOSTされた追加データ（複数のクライアントを同期するための視聴セッショントークンなど）は、セカンドスクリーンアプリから発行される後続のGETリクエストを使用して読み取ることができます。

アプリの開発に関しては、ネットワーク接続リソースのクリーンアップと終了、例外の処理、非UIブロッキングスレッドでのスレッドの起動、ネットワーク操作失敗時の適切な処理に注意を払う必要があります。

バージョン履歴

2021年4月5日：Fire TVデバイスのDIALサーバーのバージョンは、v2.2.1をサポートしています。これには、CORS認証モデルと新しい<authorizedOrigins>タグの機能強化が含まれています。現在、Fire TVのDIALサービスでは、アプリのリモートインストールやアプリの非表示（hidden）状態はサポートされていません。
2020年8月1日：Fire TVデバイスのDIALサーバーのバージョンは、v2.1をサポートしています。起動リクエストのadditionalDataUrlはすべてのFire TVデバイスで、WoW/WoLAN機能はFire TV Editionでサポートされています。