開発者コンソール

Discoveryインターフェース


Discoveryインターフェース

ユーザーが初めてアプリの使用を開始すると、AlexaはAlexa.Discoveryインターフェースを介してDiscoverディレクティブを送信し、ビデオスキルでサポートされている機能を特定します。このDiscoverディレクティブへのレスポンスで、AlexaからLambda関数に送信されるディレクティブの種類が決まります。

たとえば、チャンネル変更をサポートしていることを指定した場合、「チャンネルをPBSに変えて」とユーザーが発話すると、AlexaはChannelControllerディレクティブを送信します。しかし、このサポートを指定しない場合、Alexaはこのディレクティブを送信しません。

Discoverディレクティブ

ユーザーがAlexaスキルをAmazonアカウントに関連付けると、AlexaはDiscoverディレクティブを送信します。それ以降、AlexaはDiscoverディレクティブを定期的に送信して、検出されたデバイスを更新します。Lambda関数がDiscoverディレクティブを受け取る際、ユーザー側で行う処理はありません。

Alexa Client Libraryにおける機能の指定

手順3: Alexa Client Libraryを統合するでAlexa Client LibraryをAndroidプロジェクトに統合する際、アプリでサポートされている機能をcapabilities配列で指定する必要があります。

// スキルでサポートされている機能のリストを作成します。
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);

Alexaは、Alexa Client LibraryにあるこのcapabilitiesリストとLambda関数を参照して、アプリでサポートされている機能を特定します。

これらの機能については、以下の機能オブジェクトセクションで説明します。Alexa Client LibraryとLambdaで定義されている機能の名前は異なりますが、機能自体はほぼ同じです。

Alexa Client Libraryの機能名 ディレクティブの機能名
AlexaClientManager.CAPABILITY_CHANNEL_CONTROLLER Alexa.ChannelController
AlexaClientManager.CAPABILITY_REMOTE_VIDEO_PLAYER Alexa.RemoteVideoPlayer
AlexaClientManager.CAPABILITY_PLAY_BACK_CONTROLLER Alexa.PlaybackController
AlexaClientManager.CAPABILITY_SEEK_CONTROLLER Alexa.SeekController
AlexaClientManager.CAPABILITY_RECORD_CONTROLLER Alexa.RecordController
AlexaClientManager.CAPABILITY_KEYPAD_CONTROLLER Alexa.KeypadController

Discoverディレクティブの例

Alexa Client Libraryを初期化する際に機能のサポートを指定するだけでなく、Lambda関数でもビデオスキルの機能を指定する必要があります。Lambda関数の作成について詳しくは、手順6: Lambdaパッケージを作成・デプロイするを参照してください。

Alexaから送信されLambda関数で処理する必要があるDiscoverディレクティブの例を以下に示します。

{
    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "46e09424-9c8a-4868-9db5-6c851e967b32",
            "name": "Discover",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3"
        },
        "payload": {
            "scope": {
                "token": "[ユーザーのOauthトークン]",
                "type": "BearerToken"
            }
        }
    }
}

ペイロードの説明

payloadのフィールドについて次の表で説明します。

ペイロードの説明
フィールド 説明 データ型
scope
(必須)
リクエストの範囲(tokenおよびtypeプロパティが含まれます)。 オブジェクト
token
(必須)
OAuth2ベアラートークン。

例:b68f05cc-6a25-4134

文字列
type
(必須)
スコープの種類(現在サポートされている値はBearerTokenです)。

例: BearerToken

列挙型

レスポンスの例

LambdaはDiscoverディレクティブを受信すると、Discover.Responseを送り返して、スキルでサポートしている機能を指定する必要があります(指定はcapabilities配列で行います)。

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      “messageId”:“2aa731f1-b6dd-471c-98fe-3ac5fa5d6554”
    },
    "payload": {
        "endpoints": [
            {
                "capabilities": [
                    {
                        "interface": "Alexa.RemoteVideoPlayer",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.PlaybackController",
                        "version": "3",
                        "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous", "Rewind", "FastForward"]
                    }
                    {
                        "interface": "Alexa.SeekController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                    {
                        "interface": "Alexa.ChannelController",
                        "type": "AlexaInterface",
                        "version": "1.0"
                    },
                      {
                        "interface": "Alexa.KeypadController",
                        "type": "AlexaInterface",
                        "version": "3",
                        "keys": [
                          "INFO", "MORE", "SELECT",
                          "UP", "DOWN", "LEFT", "RIGHT",
                          "PAGE_UP", "PAGE_DOWN", "PAGE_LEFT", "PAGE_RIGHT"
                        ]
                      }  
                ]
              }
          ]
       }
  }
};

ペイロードの説明

レスポンスに含まれるpayloadオブジェクトについて次の表で説明します。

ペイロードの説明
フィールド 説明 データ型
endpoints
(必須)
ユーザーのデバイスクラウドアカウントに関連付けられたデバイスを表すエンドポイントオブジェクト配列。 オブジェクト
capabilities
(必須)
スキルがエンドポイントに対してサポートしている機能インターフェース。詳細については、以下の機能オブジェクトを参照してください。 機能オブジェクトの配列
interface
(必須)
デバイスのアクションを記述するAlexa.Interfaceの修飾名。

例: Alexa.RemoteVideoPlayer

文字列
type
(必須)
スコープの種類(現在サポートされている値はBearerTokenです)。

例: BearerToken

列挙型
version
エンドポイントでサポートしているインターフェースのバージョン。

例: 1.0

文字列
cookie
スキルアダプターで使用するデバイスに関する追加情報を表す、名前と値のペアで構成される文字列。このプロパティの内容は5000バイト以内に収める必要があります(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。

例:key1

オブジェクト
extraDetail
cookieオブジェクトのキー。

例:key1

description
(必須)
デバイスの説明。会社名または実装を含む必要があります。この値は最大128文字までです(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。

例: Amazon Streaming Media App

文字列
endpointId
(必須)
エンドポイントの識別子。たとえば、VSKTVなどです。注: ビデオスキル名と同じ値を入力することはできません。また、値の先頭にTEST_PROD_を付けて、ビデオスキル名と明確に区別することをお勧めします。

例: TEST_VSKTV

文字列
friendlyName
(必須)
ビデオスキルの実装タイプを識別するための名前。この値は最大128文字までで、特殊文字や句読点を含めることはできません。: ビデオスキル名と同じ値を入力しないでください。たとえば、ビデオスキルの名前が「ACME Media」の場合、フレンドリー名には「ACME Media」と入力しないでください。同じ名前を入力すると、エラーになります。名前に何らかの接頭辞を付けることをお勧めします(「TEST_ACME_Media」や「PROD_ACME_Media」など)。

例: TEST_VSK_FTV

文字列
manufacturerName
(必須)
デバイスのメーカーの名前。この値は最大128文字までです(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。

例: Amazon

文字列

機能オブジェクト

capabilities配列は、interfacetypeversionsupportOperationsの各プロパティをそれぞれに含むオブジェクトのリストです。たとえば、再生機能のサポートを宣言するcapabilities配列内の項目は次のようになります。

{
    "type": "AlexaInterface",
    "interface": "Alexa.PlaybackController",
    "version": "3",
    "supportedOperations" : ["Play", "Pause", "Stop", "StartOver", "Next", "Previous",
      "Rewind", "FastForward"]
}

supportedOperationsプロパティを含んでいるインターフェースはAlexa.PlaybackControllerインターフェースだけです。

keysプロパティを含んでいるインターフェースは、Alexa.KeypadControllerインターフェースだけです。

ビデオスキルでサポートされている機能とその関連ディレクティブを次の表に示します。

機能 説明
Alexa.RemoteVideoPlayer ビデオスキルは、SearchAndPlayディレクティブやSearchAndDisplayResultsディレクティブなど、RemoteVideoPlayerインターフェースのディレクティブをサポートできます。これらのディレクティブを使用すると、ユーザーはビデオコンテンツの検索や再生を行えます。たとえば、「『ブレイキング・バッド』を検索して」や「アレクサ、『ブレイキング・バッド』を見せて」などです。
Alexa.PlaybackController ビデオスキルは、Alexa.PlaybackControllerインターフェースのディレクティブをサポートできます。このインターフェースは、オーディオまたはビデオコンテンツの再生、停止、ナビゲーションに使用されます。たとえば、「アレクサ、早送りして」や「アレクサ、停止して」などです。 上記のように、PlaybackControllerインターフェースでは supportedOperationsプロパティも使用できます。supportedOperationsに使用可能な値は、 PlayPauseStopStartOverNextPreviousRewindFastForwardです。
Alexa.SeekController ビデオスキルは、Alexa.SeekControllerインターフェースのディレクティブをサポートできます。このインターフェースを使用すると、メディアタイムラインの特定の位置に移動できます。たとえば、「アレクサ、60秒早送りして」や「アレクサ、5分巻き戻して」などです(アプリでメディアアイテムの早送りまたは巻き戻しのみが可能で、タイムラインの別のポイントまでシークできない場合は、代わりにPlaybackControllerインターフェースを実装します)。
Alexa.ChannelController ビデオスキルは、Alexa.ChannelControllerインターフェースのディレクティブをサポートできます。このインターフェースは、エンターテインメントデバイスのチャンネルを変更または進めるために使用されます。たとえば、「アレクサ、チャンネルをPBSに変えて」などです。
Alexa.KeypadController ビデオスキルは、Alexa.KeypadControllerインターフェースのディレクティブをサポートできます。このインターフェースは、左右または上下へのスクロールやフォーカスされているウィジェットの選択に使用されます。たとえば、「アレクサ、右にスクロールして」などです。 上記のコード例に従って、ビデオスキルでサポートしているキーのリストを指定します。キー値には、 UPDOWNLEFTRIGHTSELECTPAGE_UPPAGE_DOWNPAGE_LEFTPAGE_RIGHTINFOMOREがあります。詳細については、この後のKeypadControllerインターフェースの機能の宣言を参照してください。KeypadControllerを使用するには、Alexa Client Libraryバージョン1.4.5以降が必要です。

KeypadControllerインターフェースの機能の宣言

アプリ内の音声ナビゲーションと選択で説明しているように、Fire TVではデフォルトで、アプリ内での音声によるスクロールと選択が可能です。DiscoveryレスポンスKeypadControllerインターフェースの機能に対するサポートを指定しない場合、VSKはデフォルトのアプリ内音声ナビゲーションおよび選択機能にフォールバックします。

一方、DiscoveryレスポンスでKeypadControllerインターフェースの機能に対するサポートを指定した場合、デフォルトのアプリ内音声ナビゲーションおよび選択機能は無効になり、音声によるスクロールと選択は、Lambdaで受信するKeyStrokeディレクティブへの応答を通じてのみ行われます。

KeypadControllerのサポートを宣言する場合は、ビデオスキルでサポートするキーのリストを指定します。キー値には、 UPDOWNLEFTRIGHTSELECTPAGE_UPPAGE_DOWNPAGE_LEFTPAGE_RIGHTINFOMOREがあります。いずれかのキーコマンドのサポートを宣言すると、すべてのキーコマンドのアクションを管理していると見なされます。つまり、一部のキーコマンドのみをサポートして、それ以外をサポートしないという宣言はできません。たとえば、UPを宣言しない場合でも、Alexaは、UP値を含んだkeystrokeペイロードを送信します。サポートされていないUP機能を補うために、デフォルトのアプリ内音声ナビゲーションおよび選択機能が働くことはありません。