開発者コンソール

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


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

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

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をダウンロードすると、Amazonのプログラム素材ライセンス契約に同意したものとみなされます。

バージョンの詳細については、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の既存バージョンを更新する方法は、以下のとおりです。

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

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

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

  • ユーザーがアプリにログインするときに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の実装例です。

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

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

次のステップ

次の 手順4: Amazon Device Messaging(ADM)を統合するに進みます。

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