手順3: Alexa Client Libraryを統合する


手順3: Alexa Client Libraryを統合する

この手順では、作成したビデオスキルを使用してFire TV対応アプリとやり取りを行えるようにします。Alexaをアプリに統合するには、Alexa Client Libraryを組み込む必要があります。Alexa Client Libraryによって、アプリはAlexaと通信し、アプリに送信されるビデオスキルAPIディレクティブを処理できます。

Fire TV対応サンプルアプリに関する注意点

Fire TV対応サンプルアプリで作業している場合は、既にAlexa Client Libraryが統合されています。サンプルアプリ: Alexa Client Libraryの表示セクションに進んで、ビデオスキルIDの構成について、詳細を確認してください。

Alexa Client Libraryによって提供される機能

Alexa Client Libraryにより、次の処理を行うことができます。

  • Android用のLogin with Amazon(LWA)を使用してAmazonで認証する。
  • 既存のEchoからFire TVへの関係を推測することで、スキルとEchoデバイスを自動的にペアリングする(ユーザーがAlexaアプリでスキルを追加する必要がありません)。
  • アプリのライフサイクルイベントを管理し、Alexaに送り返す(ユーザーが音声に対応したFire TV対応アプリを操作する際に、Alexaがよりインテリジェントな判断を行うのに役立ちます)。
  • アプリで受け取ったディレクティブに対するレスポンスをAlexaに送信する。

前提条件

Node.jsとNPMをある程度理解していると役立ちますが、この段階ではこの分野の専門知識は必要ありません。Node.jsバージョン8.1以降を使用していることは確認してください。Node.jsとNPMが既にインストールされているかどうかを確認するには、node -vおよびnpm -vと入力します。

アプリで処理する必要があるAlexaディレクティブの詳細については、手順7: Alexaディレクティブを解釈して応答するを参照してください。

手順3.1: Alexa Client LibraryをFire TV対応アプリに追加する

Android StudioでGradleを使用している場合は、Alexa Client Libraryの統合にリリース済みSDKのAndroid Archive(AAR)ファイルを利用できます。Android StudioでプロジェクトにAlexa Client Library(AlexaClientLib.aar)を追加する方法は、以下のとおりです。

  1. Alexa Client LibraryのZIPファイルをダウンロードし、解凍します。このzipファイルにはAlexaClientLib.aarファイルが含まれています。
  2. Android Studioのプロジェクトで、[File] > [New] > [New Module] の順にクリックします。
  3. [Import .JAR/.AAR Package] を選択し、[Next] をクリックします。
  4. [File name] フィールドでAlexaClientLib.aarファイルを選択し、[Open] > [Finish] の順にクリックします。
  5. [File] > [Project Structure] の順にクリックします。
  6. 左側のメニューにある [Modules] で、[app] を選択します。
  7. [Dependencies] タブをクリックします。
  8. 必須コンポーネントのリストにAlexaClientLibが表示されない場合は、下の [+] ボタンをクリックし、[3.Module dependency] を選択します。
  9. リストから [AlexaClientLib] を選択します。

手順3.2: ProGuardを構成する

AndroidプロジェクトでProGuardを使用している場合は、次のように更新します。

  1. ProGuardルールファイルを探します。
  2. 次の構成を追加します。

    -libraryjars ../AlexaClientLib
    
    # LWAとAlexa Client Libraryのクラスを保持します
    -dontwarn com.amazon.identity.auth.device.**
    -dontwarn com.amazon.alexa.vsk.clientlib.**
    
    -keep class com.amazon.identity.auth.device.** { *; }
    -keep class com.amazon.alexa.vsk.clientlib.** { *; }
    

手順3.3: Alexa Client Libraryを初期化する

Alexa Client Libraryが正しく動作するように、Alexa Client Libraryを初期化する必要があります。初期化は以下の手順に沿って行ってください。

  1. ApplicationクラスでinitializeAlexaClientLibrary()を宣言します。以下のコードサンプルを参照してください。initializeAlexaClientLibrary()onCreate()から呼び出してください。

    public class YourApplication extends Application {
    		@Override
        protected void onCreate() {
            super.onCreate();
    
            // 最初にAlexa Client Libraryを初期化します。
            initializeAlexaClientLibrary();
         }
    
    
        public static void initializeAlexaClientLibrary(Activity mainActivity) {
            // AlexaClientManagerの共有インスタンスを取得します
            AlexaClientManager clientManager = AlexaClientManager.getSharedInstance();
    
            // スキルIDと機能のリストを収集します
            final String alexaSkillId = "YOUR_SKILL_ID";
    
            // スキルでサポートされている機能のリストを作成します。
            List<String> capabilities = new ArrayList<>();
            capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
            capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
            capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
            capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);
    
            clientManager.initialize(mainActivity,
                alexaSkillId,
                AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
                capabilities);
        }
    }
    

    上記のサンプルコードでは、これらの機能に対するサポートを宣言しています。

    capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
    capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
    capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
    capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);
    

    アプリがこれらの機能をサポートしていない場合は、これらの行を省略してください。Alexaは、これらの機能に関連するディレクティブを送信します。たとえば、 CAPABILITY_CHANNEL_CONTROLLERを指定した場合、ユーザーが「チャンネルをPBSに変えて」と言うと、AlexaからChangeChannelディレクティブが送信されます。 詳細については、Discoverインターフェースを参照してください。

  2. 上記のコードで、YOUR_SKILL_IDを独自のスキルIDに置き換えます(手順1.1: ビデオスキルの作成を始めるでコピーしたものです)。

手順3.4: ダウンチャンネルサービスを初期化する

Alexaサービスからディレクティブを受け取るには、以下のサンプルコードに従ってアプリでダウンチャンネルサービスを構築する必要があります。ダウンチャンネルは、主にクラウドが発信するディレクティブをFire TV対応アプリに配信するために使用されるストリームです。このサービスはAmazon Device Messagingを使用します。この統合については、手順4: Amazon Device Messaging(ADM)を統合するで詳しく説明します。

ダウンチャンネルサービスについては、以下の点に注意してください。

  • ダウンチャンネルサービスの準備ができたら、次のパラメーターを指定してsetDownChannelReady() APIを呼び出します。

    • 最初のパラメーター(isDownChannelReady)は、ダウンチャンネルの準備ができていることを示すtrueである必要があります。
    • 2番目のパラメーター(appInstanceId)は、アプリインスタンスを一意に識別する文字列である必要があります。Amazon Device Messaging(ADM)を使用している場合は、このパラメーターにアプリのADM登録IDを使用します(ADMを使用しない場合は、別の方法を使用できます)。
  • ダウンチャンネルサービスのステータスが変わったら、毎回適切なステータスフラグ値を指定してsetDownChannelReady() APIを呼び出します。
  • 次に示すように、アプリの作成時にADMサービスを初期化(initializeAdm();)します。

以下のコードは、ADMの実装例です。

public class YourApplication extends Application {

    @Override
    protected void onCreate() {
      super.onCreate();

      // 最初にAlexa Client Libraryを初期化します。
      initializeAlexaClientLibrary();

      // ADMを初期化します。
      initializeAdm();
    }

    private void initializeAdm() {
      try {
       final ADM adm = new ADM(this);
          if (adm.isSupported()) {
            if (adm.getRegistrationId() == null) {
              // ADMの準備ができていません。ADM登録を開始するには、
              // startRegister() APIを呼び出す必要があります。ADMは、登録されたADM IDを使用して
              // ADM登録が完了したときにADMハンドラーサービスでonRegister() APIを呼び出します。
              adm.startRegister();
            } else {
              // [重要]
              // ADMダウンチャンネルは既に利用可能です。これは、アプリが再起動された場合の
              // 一般的なケースです。Fire TVのADMマネージャーは、以前の
              // ADM登録情報をキャッシュし、アプリが再起動済みと
              // 識別されるとすぐにそれを提供します。
              //
              // 取得したADM登録IDをAlexa Client Libraryに提供する必要があります。
              final String admRegistrationId = adm.getRegistrationId();
              Log.i(TAG, "ADM registration Id:" + admRegistrationId);

              // 取得したADM登録IDを指定します。
              final AlexaClientManager alexaClientManager = AlexaClientManager.getSharedInstance();
              alexaClientManager.setDownChannelReady(true, admRegistrationId);
           }
         }
       } catch (Exception ex) {
          Log.e(TAG, "例外が発生しADMの初期化に失敗しました", ex);
      }
   }
}

手順3.5: ユーザーがサインイン/サインアウトした際にアプリのAlexaターゲティングを有効化/無効化する

関数setAlexaEnabled()は、ユーザーがターゲット可能なエンドポイントとしてアプリインスタンスを有効または無効にするために使用します。手順は以下のとおりです。

  • ユーザーがアプリにログインするときにsetAlexaEnabled(true)を呼び出します。
  • ユーザーがログアウトするときにsetAlexaEnabled(false)を呼び出します。
// ユーザーは有効な定期購入でログインしています
AlexaClientManager.getSharedInstance().setAlexaEnabled(true);

// ユーザーがログアウトしているか、有効な定期購入がありません
AlexaClientManager.getSharedInstance().setAlexaEnabled(false);

このルールの唯一の例外は、アプリにユーザーログインがない場合です。つまり、ユーザーがログインしているか、特定の定期購入があるかに関係なく、ユーザーがコンテンツを利用できる場合です。

サンプルアプリ: Alexa Client Libraryの表示

サンプルアプリでは、Alexa Client Libraryを組み込むための上記の手順はすべて構成されているため、ここでコーディングを行う必要はありません。ただし、ビデオスキルIDは構成する必要があります。サンプルアプリでビデオスキルIDを構成するには、次の手順に従います。

  1. Shiftキーを2回押して、TenFootApp.javaを検索します。
  2. 使用するビデオスキルIDでALEXA_SKILL_IDの値をカスタマイズします。以下に例を示します。

    private static final String ALEXA_SKILL_ID = "amzn1.ask.skill.544641fd-b4b3-40ab-a9f6-c9757bda68b6";
    

    これで完了です。サンプルアプリの統合についてもう少し詳しく確認する場合は、下記をご覧ください。統合プロセスの次のステップに進むことも可能です。

サンプルアプリの統合について確認する

サンプルアプリでAlexa Client Library、ADM、ダウンチャンネルサービスの初期化に関する上記のコードをいくつか確認するには、次の操作を行います。

  • AlexaClientLibモジュール名をダブルクリックします。[Modules] タブが選択された状態で、Android Studioの [Project Structure] ダイアログボックスが開きます。[Dependencies] タブをクリックすると、リストにAlexaClientLibが表示されます。
  • Shiftキーを2回押してproguardを検索し、proguard-rules.proファイル(AMZNMediaPlayerComponent内)を表示します。
  • Shiftキーを2回押して、TenFootApp.javaTVUIComponent内)を検索します。これは、initializeAlexaClientLibrary()でAlexa Client Libraryを初期化するコードです。
  • 同じTenFootApp.javaファイルにはinitializeAdm()でADMを初期化するコードがあるので探してみてください。

次のステップ

次の手順の 手順4: Amazon Device Messaging(ADM)を統合するで詳しく説明します。