DIALの統合
Amazon Fire TVデバイスは、Whisperplayサービスを介してDIAL(Discovery-and-Launch)プロトコルをサポートします。
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マニフェストを変更します。詳細については、手順A: Androidマニフェストを変更するを参照してください。
- ファーストスクリーンアプリであるFire TV対応アプリで、
whisperplay.xml
ファイルをアプリのリソースに追加します。詳細については、手順B: Whisperplay.xmlファイルを追加するを参照してください。 - ファーストスクリーンアプリであるFire TV対応アプリのコード内で、起動インテントとエクストラを処理します。この手順は、セカンドスクリーンアプリがDIAL起動リクエストでペイロードを送信する場合や、DIALサーバーを介してFire TV対応アプリから追加データを受信する場合にのみ必要です。詳細については、手順C: 起動インテントと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/
ディレクトリにあるリソースに追加します。
<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>
<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
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でサポートされています。
Last updated: 2021年11月12日