開発者コンソール
ログイン
ログイン
開発者コンソール

Amazonカタログ統合用のCordovaプラグイン

Amazonカタログ統合用のCordovaプラグイン

Amazonカタログ統合用のCordovaプラグインを使用すると、HTML5ウェブアプリをAmazonカタログと統合できます。そうすることで、アプリ内のメディアを音声検索できるようになり、Fire TVの検索結果にアプリのコンテンツが表示されます。

ただし、コンテンツ申請の標準プロセスに従ってアプリのコンテンツをAmazonカタログに申請する必要があります。このプラグインは、Fire TVランチャーにインテントを追加して、アプリにビデオ再生機能があることを示すことのみを目的としています。

Cordovaとこのプラグインについて

このAmazonカタログ用プラグインは、Apache Cordovaをベースとしています。Apache Cordovaは、HTML5ウェブアプリでAndroidのネイティブ機能をウェブアプリに追加できるラッパーを提供しています。Cordovaを使用することで、ウェブアプリのAPKファイルを作成できます。

このプラグインは、HTML5ウェブアプリをAmazonカタログに統合させるために開発されました（Fire TVで音声検索またはグローバルテキスト検索を実行したときにアプリ内のメディアの検索結果を表示させるには、カタログの統合が必要です）。 このプラグインがないと、ウェブアプリをAmazonカタログに組み込めません。

前提条件 — Cordovaプロジェクトの追加

次のセクション（Amazonカタログ統合用のCordovaプラグインをインストールする方法）に記載の手順では、ウェブアプリにCordovaプロジェクトを既に追加していることを前提としています。まだ追加していない場合は、CordovaのドキュメントのCreate the App（英語のみ）で詳細を参照してください。

Cordovaプロジェクトを作成するには、最初にnpmのインストールとCordovaコマンドラインツールのインストールを行う必要があります。

npmとCordovaコマンドラインツールをインストールした後、次のようにCordovaをウェブアプリプロジェクトに追加します。

cordova create hello com.example.hello HelloWorld

このコマンドでは、パッケージ名helloをプロジェクトに対して指定しています。「hello」という名前の新しいディレクトリがウェブアプリのディレクトリ内に作成されます。このディレクトリに含まれるファイルの中には、アプリが処理できるインテントを一覧表示するconfig.xmlファイルがあります。

さらに必要な条件として、Cordovaプロジェクト用のAndroidプラットフォームを追加する必要があります。

cordova platform add android

cordova platform add androidコマンドはCordovaプロジェクトディレクトリから実行してください（「Error: Current working directory is not a Cordova-based project.」というエラーが発生した場合は、 インストールしようとしているディレクトリが誤っています）。

Cordovaプロジェクトのconfig.xmlファイルでは、コンテンツのソースを<content>タグでリストする必要があります。例：

<content src="https://firetv.acme.com/" />

これらの前提条件を満たした後で、プラグインをインストールして構成する方法の詳細について次のセクションを参照してください。

Amazonカタログ統合用のCordovaプラグインをインストールする方法

  1. （省略可能）ノード用パッケージマネージャーのplugmanをインストールして、コンピューター上でグローバルに利用できるようにします。

    npm install -g plugman

  2. Fire TVランチャー統合用CordovaプラグインをGitHubからコピーします。このフォルダを適切な場所に配置します。

  3. 次のコマンドを使用してAmazonカタログ用のCordovaプラグインをインストールします。下のパラメーター表に基づいてプラグインのパラメーター値をカスタマイズしてください。

    plugman install --platform android --project YOUR_CORDOVA_PROJECT/platforms/android --plugin LOCATION_OF_PLUGIN --variable DISPLAY_NAME="アプリの表示名" --variable PARTNER_ID="アプリのパートナーID" --variable DEFAULT_SIGNEDIN_STATUS="TRUEまたはFALSE" ;

    実際のパラメーター値が構成された例は次のとおりです。

    plugman install --platform android --project ./platforms/android --plugin ../../CI-Plugin-For-Release --variable DISPLAY_NAME="ACME" --variable PARTNER_ID="ACME" --variable DEFAULT_SIGNEDIN_STATUS="TRUE" ;

    plugmanを使用していない場合は、デフォルトのCordovaコマンドラインツールを使用してプラグインをインストールできます。

    cordova plugin add LOCATION_OF_PLUGIN --variable PARTNER_ID="アプリのパートナーID" --variable DISPLAY_NAME="アプリの表示名"

    プラグインのパラメーター

    各パラメーターとその詳細は下表のとおりです。

    パラメーター 説明 デフォルト値
    --project YOUR_CORDOVA_PROJECT Cordovaディレクトリのファイルの場所。Cordovaディレクトリからコマンドを実行している場合は、「.」を使用して現在のディレクトリを示します。 なし（必須）
    --plugin LOCATION_OF_PLUGIN Cordova Amazonカタログプラグインのディレクトリの場所 （注： ベータ版では、プラグインはローカルにダウンロードするzipファイルとして提供されます）。 なし（必須）
    --variable DISPLAY_NAME="アプリの表示名" アプリの名前。 なし（必須）
    --variable PARTNER_ID="アプリのパートナーID" パートナーID（Amazonが提供）は、カタログの統合でCDFファイルのパートナーフィールドに使用するIDと同じです。このIDはアプリに対しては一意ですが、個人や組織に対しては一意ではありません。ユーザーまたはユーザーの組織が複数のFire TV対応アプリを持っている場合は、それぞれのアプリでパートナーIDが異なります（詳細については、「手順1：アプリにFire TVランチャーを統合する」の「インテントエクストラ」を参照してください）。 なし（必須）
    --variable DEFAULT_SIGNEDIN_STATUS="TRUEまたはFALSE" アプリに送られるインテントを変更します。デフォルトでは、signIn/signoutがウェブアプリから呼び出されない場合、アプリは対応するインテントを送信します。アプリにサインインのフローがない場合は、この値をTRUEに設定します（詳細については、手順1：アプリにFire TVランチャーを統合するを参照してください）。 false
    --variable VIDEO_ID_IS_URI="TRUEまたはFALSE" コンテンツIDがURI形式かどうかに応じて、コンテンツIDを正常に取得できるように、アプリの動作を変更します（詳細については、手順2： カタログのディープリンクを検証するを参照してください）。 true
    --variable DEEP_LINK_REGEX="正規表現" インテントデータに含まれるコンテンツIDの解析に使用される正規表現。コンテンツIDは最初のキャプチャグループにあるはずです。たとえば、コンテンツIDがmyapp://watch/content/123456という形式で渡されている場合、そのコンテンツID123456を解析する正規表現は^myapp:\\/\\/watch\\/content\\/([0-9]+)$となります。指定されていない場合は、デフォルトで文字列全体が送られます（詳細については、手順2： カタログのディープリンクを検証するを参照してください）。 ^(.+)$

    プラグインが正常に追加されると、次の応答が返されます。

    Installing "com.amazon.cordova.plugins.launcher" for android
Adding intent-filter to Android Manifest
New Activity Extending CordovaActivity created
New Activity package adjusted to match project package
Main Activity Parent Class changed to DeepLinkingCordovaActivity

    プラグインファイルがCordovaプロジェクトに追加されます（<CORDOVA_PROJECT>/platforms/android/src/com/amazon参照）。

  4. ディープリンクを許可するようにメインアクティビティを編集します。

    Cordovaプロジェクトをカスタマイズしていて、メイン起動アクティビティが不明な場合は、次のインテントフィルターがあるAndroidマニフェスト（platforms/android/AndroidManifest.xml）でアクティビティを調べることで確認できます。

    <intent-filter android:label="@string/launcher_name">
  <action android:name="android.intent.action.MAIN" />
  <category android:name="android.intent.category.LAUNCHER" />
</intent-filter>

    CordovaActivityではなくDeepLinkingCordovaActivityを拡張するように、メインアクティビティ（例：MainActivity.java）を変更します。DeepLinkingCordovaActivityがメインアクティビティと同じディレクトリにあることを確認してください。また、DeepLinkingCordovaActivityのパッケージ名がメインアクティビティと同じであることも確認します。

    DeepLinkingCordovaActivity.javaが見つからない場合は、プラグインのディレクトリ（src/com/amazon/cordova/plugins/launcher/）からメインアクティビティと同じディレクトリにコピーします。

  5. 起動パラメーターの受け取りを許可するよう、ウェブアプリを編集します。

    特定のコンテンツの起動インテントをアプリが受け取ると、抽出されたコンテンツIDがクエリパラメーターとして、標準の起動URLに追加されます。クエリパラメーターの名前はamazonLauncherIntegrationContentIdです。

    このクエリパラメーターを受け取れるように、ウェブアプリに機能を実装します。アプリは、amazonLauncherIntegrationContentIdパラメーターを受け取ると、contentId値を直接プレーヤーにルーティングします。アプリを起動するとすぐに、ユーザーが何も操作しなくても、選択されたコンテンツの再生が始まるはずです。

    また、アップロードしたカタログと利用可能なコンテンツが同期されない状況を考えて、アプリ内にエラー処理を実装することも重要です。有用なエラーメッセージが表示されてから適切な場所にリダイレクトされるようにすれば、ユーザーエクスペリエンスを最大限に高められることがわかっています。

  6. プラグインを正常に追加できたら、アプリの構築に取りかかることができます。次のコマンドを使用して構築します。

    cordova build android

    構築が成功すると、CordovaによってAPKファイルが生成されます。このファイルをFire TVデバイスにサイドロードしてテストできます。APKをサイドロードするには、adbを使用します （例：adb install /<path-to-apk>/android-debug.apk）。詳細については、アプリをインストールして実行する方法を参照してください。

    アプリをサイドロードした後、機能をテストできます。リモコンのマイクボタンを押して、アプリからメディアコンテンツを検索します。検索結果にはアプリのメデイアと一致したメディアが表示されます。画像タイトルをクリックすると、アプリが起動され、コンテンツが再生されます。

  7. signedIn/signedOutステータスを変更するには、アプリのonDeviceReadyハンドラーで、cordova.require('com.amazon.cordova.plugins.launcher')の結果を保存します（例：this.launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');）。

    launcherPluginオブジェクトには次の2つの関数があります。

    • isSignedIn(successCallback(status), errorCallback)
    • setSignedInStatus(status, successCallback, errorCallback)

    例：

    var launcherPlugin;

function myHandlerFunction(){
      launcherPlugin = cordova.require('com.amazon.cordova.plugins.launcher');
}
document.addEventListener(“deviceready”,myHandlerFunction, false)

    onDeviceReadyイベントは、Cordovaの実行が終了し、Cordovaに関連するコードの実行を開始できることをウェブアプリに通知します（SignedInステータスの設定など）。