開発者コンソール

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


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

Alexaをアプリに統合するには、Alexa Client Libraryを組み込む必要があります。Alexa Client Libraryによって、アプリはAlexaと通信し、アプリに送信されるビデオスキルAPIディレクティブを処理できます。

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

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

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

Fire TV対応サンプルアプリで作業している場合は、既にAlexa Client Libraryが統合されています。次の 手順4: Amazon Device Messaging(ADM)を統合するに進んでください。構成についての詳細を確認する場合は、サンプルアプリでの構成の確認に進んでください。

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

Alexa Client Libraryのフィールド、メソッド、実装要件について詳しく説明したJavadocについては、Class AlexaClientManagerを参照してください。以下のセクションでは、このJavadocで説明されている実装について説明します。

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] を選択します。

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

アプリの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を初期化します。
        initializeAlexaClient();

        ...
    }

    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);

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

上記のコードについては、次の点に注意してください。

  • 登録ユーザーにのみAlexaを有効にする(clientManager.setAlexaEnabled(true);を設定する)ことをお勧めします。上記のインラインコメントに、アクティブなユーザーがアプリにログインするまで、このステップを遅らせることができると書かれているのは、これを指しています。

  • スキルステージはSKILL_STAGE_DEVELOPMENTに設定されています。この後の開発プロセスで、アプリを公開する準備ができたら(手順12: アプリを公開する)、AlexaClientManager.SKILL_STAGE_DEVELOPMENTAlexaClientManager.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_CONTROLLERAlexaClientManager.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_RECORD_CONTROLLER Alexa.RecordController StartRecording
StopRecording
CAPABILITY_KEYPAD_CONTROLLER Alexa.KeypadController SendKeystroke

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

スキルIDのカスタマイズ

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

final String alexaSkillId = "YOUR_SKILL_ID";

ユーザーがログインまたはログアウトするときにAlexa Client Libraryを有効または無効にする方法

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

  • ユーザーがアプリにログインするときにsetAlexaEnabled(true)を呼び出します。
  • ユーザーがログアウトするときに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の実装例です。

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);
      }
   }
}

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

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

サンプルアプリでの構成の確認

サンプルアプリの統合についてもう少し詳しく確認する場合は、下記を参照してください。統合プロセスの次のステップに進むことも可能です。サンプルアプリでAlexa Client Libraryの統合および初期化に関する上記のコードを確認するには、次の操作を行います。

  • 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)を統合するに進みます。

問題が発生して続行できない場合は、トラブルシューティングを参照してください。