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

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

Fire TV対応サンプルアプリには、既にAlexa Client Libraryバージョン1.4.6が統合されています（[Project] ペインに「AlexaClientLib」モジュールが表示されます）。 Alexa Client Libraryのバージョンが上がっている場合は、Fire TV対応アプリでAlexa Client Libraryを更新できます。また、このサンプルアプリのMainActivity.javaファイルとVSKFireTVMessageHandler.javaファイルを参照して、Alexa Client Libraryの統合と初期化の方法を確認することもできます。それ以外の場合は、次の手順4： Amazon Device Messaging（ADM）を統合するに進みます。

Alexa Client Libraryのダウンロード
Alexa Client Libraryについて
Alexa Client LibraryをFire TV対応アプリで更新する方法
Alexa Client LibraryをFire TV対応アプリに追加する方法
ProGuardを構成する
アプリのonCreateからAlexa Client Libraryを初期化する方法
次のステップ

Alexa Client Libraryのダウンロード

Alexa Client Libraryは以下からダウンロード可能です。

Alexa Client Libraryをダウンロードすると、AmazonのProgram Materials License Agreementに同意したものとみなされます。

バージョンの詳細については、Alexa Client Libraryリリースノートを参照してください。

Alexa Client Libraryについて

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

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

Alexa Client Libraryのフィールド、メソッド、実装要件を詳しく説明したJavadocについては、Class AlexaClientManager（英語のみ）を参照してください。

Alexa Client LibraryをFire TV対応アプリで更新する方法

Android StudioのプロジェクトでAlexa Client Libraryの既存バージョンを更新する方法は、以下のとおりです。

Alexa Client Libraryのzipファイルをダウンロードし、解凍します。このzipファイルには、AlexaClientLib.aarファイルが含まれています。
Android Studioで [AlexaClientLib] モジュールを右クリックし、[Reveal in Finder] （Mac）または [Show in Explorer] （Windows）を選択します。
AlexaClientLibフォルダを開きます。
新しいAlexaClientLib.aarファイルをドラッグし、既存のファイルと置き換えます。ファイルを上書きするかどうかを確認するメッセージが表示されたら、[Replace] を選択します。

Alexa Client LibraryをFire TV対応アプリに追加する方法

Android StudioのプロジェクトにAlexa Client Library（AlexaClientLib.aar）を追加する方法は、以下のとおりです。

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

ProGuardを構成する

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

ProGuardルールファイルを探します。

次の構成を追加します。

-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.** { *; }

アプリのonCreateからAlexa Client Libraryを初期化する

Alexa Client Libraryが正しく動作するように、Alexa Client Libraryを初期化する必要があります。ApplicationクラスでinitializeAlexaClientLibrary()を宣言します。以下のコードサンプルを参照してください。initializeAlexaClientLibrary()はonCreate()から呼び出してください。

public class YourApplication extends Application {

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

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

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

      // （オプション）VSKによってバックグラウンドで自動ペアリングがすぐに開始されるように、Alexa Client Libraryを有効にします。
      // こうすると、ユーザーがAlexa Voice Serviceを使用可能になるまでの時間を短縮できます。
      // アクティブなユーザーがアプリにログインするまで、このステップを遅らせることができます。
      AlexaClientManager.getSharedInstance().setAlexaEnabled(true);
    }

    private void initializeAlexaClient() {
        // AlexaClientManagerの共有インスタンスを取得します。
        AlexaClientManager clientManager = AlexaClientManager.getSharedInstance();

        // スキルIDを収集します。
        final String alexaSkillId = "YOUR_SKILL_ID";

        // スキルでサポートされている機能のリストを作成します。
        List capabilities = new ArrayList<>();
        capabilities.add(AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER);
        capabilities.add(AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER);
        capabilities.add(AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER);
        capabilities.add(AlexaClientManager.CAPABILITY_SEEK_CONTROLLER);

        // initialize()を呼び出してAlexa Client Libraryを初期化します。
        clientManager.initialize(getApplicationContext(),
                alexaSkillId,
                AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
                capabilities);
    }

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

              // 取得したADM登録IDをAlexa Client Libraryに提供する必要があります。
              final String admRegistrationId = adm.getRegistrationId();
              Log.i("ADM登録ID：" + admRegistrationId);
              // 取得したADM登録IDを指定します。
              AlexaClientManager.getSharedInstance().setDownChannelReady(true, admRegistrationId);
           }
         }
       } catch (Exception ex) {
          Log.e(TAG, "例外が発生しADMの初期化に失敗しました", ex);
      }
   }
}

全般的な注意事項

スキルステージはSKILL_STAGE_DEVELOPMENTに設定されています。この後の開発プロセスで、アプリを公開する準備ができたら（手順12：アプリを公開する）、AlexaClientManager.SKILL_STAGE_DEVELOPMENTをAlexaClientManager.SKILL_STAGE_LIVEに変更します。
初期化が呼び出される前にイベント（たとえば、アプリのバックグラウンド化／フォアグラウンド化などの可視性の変更など）が発生した場合、アプリは強制停止後に再起動されるまで音声に応答しません。

機能の宣言

上記のサンプルコードでは、次の機能のサポートを宣言しています。

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は、ここで示した機能に関連するディレクティブを送信します。たとえば、AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLERを指定した場合、ユーザーが「チャンネルをPBSに変えて」と言うと、AlexaからChangeChannelディレクティブが送信されます。機能を宣言していないと、Alexaは、その機能に関連するディレクティブを送信しません。詳細については、Discoveryインターフェースを参照してください。

アプリがサポートしていない機能については、上記のコードからその機能を削除してください。また、AlexaClientManager.CAPABILITY_RECORD_CONTROLLERやAlexaClientManager.CAPABILITY_KEYPAD_CONTROLLERの機能をアプリでサポートしている場合は、これらのAPIを追加することもできます。機能については、以下の表を参照してください。

Alexa Client Libraryの機能	ディレクティブの機能	ディレクティブ
`CAPABILITY_CHANNEL_CONTROLLER`	`Alexa.ChannelController`	`ChangeChannel`
`CAPABILITY_REMOTE_VIDEO_PLAYER`	`Alexa.RemoteVideoPlayer`	`SearchAndDisplayResults` `SearchAndPlay`
`CAPABILITY_PLAY_BACK_CONTROLLER`	`Alexa.PlaybackController`	`Pause` `Play` `Stop` `Resume` `Next` `Previous` `FastForward` `Rewind` `StartOver`
`CAPABILITY_SEEK_CONTROLLER`	`Alexa.SeekController`	`AdjustSeekPosition`
`CAPABILITY_KEYPAD_CONTROLLER`	`Alexa.KeypadController`	`SendKeystroke`

Alexa Client Libraryで定義済みの定数（List<String> capabilitiesなど）を使用せずに機能を宣言する場合は、その機能の正確な文字列名を使用して宣言できます。たとえば、次のようにGUIショートカットの「Launcher」機能を追加します。capabilities.add("Alexa.Launcher");

注：ここでアプリのコードに機能を設定するだけでなく、Lambdaコードにもこれらの機能を追加する必要があります。これは、後の手順で設定します。Lambda関数はDiscoverディレクティブを受信すると、Discover.Responseを送り返して、スキルでサポートしている機能を指定する必要があります。Discoverディレクティブのドキュメントでレスポンスの例を参照してください。

スキルIDのカスタマイズ

上記のコードで、YOUR_SKILL_IDを独自のビデオスキルIDに置き換えます。このIDは、手順1：ビデオスキルを作成してデバイスをセットアップするでコピーしたものです。

final String alexaSkillId = "YOUR_SKILL_ID";

関数setAlexaEnabled()は、ユーザーがターゲット可能なエンドポイントとしてアプリインスタンスを有効または無効にするために使用します。登録ユーザーにのみAlexaを有効にする（setAlexaEnabled(true)を設定する）ことをお勧めします（コード内のインラインコメントに、「アクティブなユーザーがアプリにログインするまでこのステップを遅らせることができる」と書かれているのは、これを指しています）。手順は以下のとおりです。

ユーザーがアプリにログインするときにsetAlexaEnabled(true)を呼び出します。
ユーザーがログアウトするときにsetAlexaEnabled(false)を呼び出します。

重要： ユーザーによる直接操作へのレスポンスではsetAlexaEnabledをfalseに設定できますが、HDMIイベントなどの自動イベントへのレスポンスではこの設定はできません。アプリがバックグラウンドに移行したときや終了したときは、setAlexaEnabled(false)を呼び出さないでください。

以下にコードの例を示します。

public class YourSigninActivity extends Activity {
    private void onUserSignedIn() {
        // ユーザーがログインしたら、Alexa Client Libraryを有効にします。
        AlexaClientManager.getSharedInstance().setAlexaEnabled(true);
    }

    private void onUserSignedOut() {
        // ユーザーがログアウトしたら、Alexa Client Libraryを無効にします。
        AlexaClientManager.getSharedInstance().setAlexaEnabled(false);
    }
}

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

ダウンチャンネルサービスの構築

Alexaサービスからディレクティブを受け取るには、上記のサンプルコードに従ってアプリでダウンチャンネルサービスを構築する必要があります。ダウンチャンネルは、主にクラウドが発信するディレクティブをFire TV対応アプリに配信するために使用されるストリームです。ダウンチャンネルサービスについては、以下の点に注意してください。

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

最初のパラメーター（isDownChannelReady）は、ダウンチャンネルの準備ができていることを示すtrueである必要があります。
2番目のパラメーター（appInstanceId）は、アプリインスタンスを一意に識別する文字列である必要があります。Amazon Device Messaging（ADM）を使用している場合は、このパラメーターにアプリのADM登録IDを使用します（ADMを使用しない場合は、別の方法を使用できます）。

ダウンチャンネルサービスのステータスが変わったら、毎回適切なステータスフラグ値を指定してsetDownChannelReady() APIを呼び出します。

次に示すように、アプリの作成時にADMサービスを初期化（initializeAdm();）します。上記のコードは、ADMの実装例です。

ダウンチャンネルの準備ができたら、アプリインスタンスIDを指定します。

public class YourADMHandler extends ADMMessageHandlerBase {
     @Override
     protected void onRegistered(final String registrationId) {
         // [重要]
         // ADMダウンチャンネルの準備が完了しています。取得したADM登録IDを使用して、ダウンチャンネルを準備完了に設定します。
         AlexaClientManager.getSharedInstance().setDownChannelReady(true, registrationId);
     }
 }

警告： 現在のユーザーがコンテンツにアクセスできないことが判明している場合を除き、アプリの初期化中にfalseを渡さないでください。この状態のオンとオフを切り替えると、Alexaがエンドポイントの登録を解除して再登録するため、スキルに意図しない結果が生じます。

次のステップ

次の手順4： Amazon Device Messaging（ADM）を統合するに進みます。

問題が発生して続行できない場合は、クラウド側の統合に関するトラブルシューティングを参照してください。

Last updated: 2022年3月16日