Discoveryインターフェース
ユーザーが初めてアプリの使用を開始すると、AlexaはAlexa.Discovery
インターフェースを介してDiscover
ディレクティブを送信し、ビデオスキルでサポートされている機能を特定します。このDiscoverディレクティブへのレスポンスで、AlexaからLambda関数に送信されるディレクティブの種類が決まります。
たとえば、チャンネル変更をサポートしていることを指定した場合、「チャンネルをPBSに変えて」とユーザーが発話すると、AlexaはChannelController
ディレクティブを送信します。 しかし、このサポートを指定しない場合、Alexaはこのディレクティブを送信しません。
- Discoverディレクティブ
- Alexa Client Libraryにおける機能の指定
- Discoverディレクティブの例
- ペイロードの説明
- レスポンスの例
- ペイロードの説明
- capabilities配列
- KeypadControllerインターフェースの機能の宣言
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関数を参照して、アプリでサポートされている機能を特定します。
機能については、以下のcapabilities配列セクションで説明します。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_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ベアラートークン。
例: |
文字列 |
type (必須) |
スコープの種類(現在サポートされている値は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"
]
},
{
"interface": "Alexa.Launcher",
"type": "AlexaInterface",
"version": "3.1",
"configuration": {
"catalogs": [],
"targets": [
{
"name": "profile",
"identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw="
},
{
"name": "settings",
"identifier": "primevideo.PPCALkmhnlkChAFHNtGsxM95rZw"
},
{
"name": "browse",
"identifier": "primevideo.Byb9lM7y5cjvtKF2q1i0samxtKc="
},
{
"name": "watchlist",
"identifier": "primevideo.OUlgBIlNyZkxB5+MPP+MPo/Yl5Y"
},
{
"name": "movies",
"identifier": "primevideo.zYYLxEVy5FSUC6oCrza6ly7FWLg"
}]
}
}
]
}
]
}
}
};
ペイロードの説明
レスポンスに含まれるpayload
オブジェクトを次の表に示します。
フィールド | 説明 | データ型 |
---|---|---|
endpoints (必須) |
ユーザーのデバイスクラウドアカウントに関連付けられたデバイスを表すエンドポイントオブジェクト配列。 | オブジェクト |
capabilities (必須) |
スキルがエンドポイントに対してサポートしている機能インターフェース。詳細については、以下の機能オブジェクトを参照してください。 | 機能オブジェクトの配列 |
interface (必須) |
デバイスのアクションを記述するAlexa.Interface の修飾名。
例: |
文字列 |
type (必須) |
スコープの種類(現在サポートされている値はBearerToken です)。
例: |
列挙型 |
version (省略可能) |
エンドポイントでサポートしているインターフェースのバージョン。
例: |
文字列 |
cookie (省略可能) |
スキルアダプターで使用するデバイスに関する追加情報を表す、名前と値のペアで構成される文字列。このプロパティの内容は5000バイト以内に収める必要があります(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。
例: |
オブジェクト |
extraDetail (省略可能) |
cookie オブジェクトのキー。
例: |
|
description (必須) |
デバイスの説明。会社名または実装を含む必要があります。この値は最大128文字までです(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。
例: |
文字列 |
endpointId (必須) |
エンドポイントの識別子。たとえば、VSKTV などです。注: ビデオスキル名と同じ値を入力することはできません。また、値の先頭にTEST_ やPROD_ を付けて、ビデオスキル名と明確に区別することをお勧めします。
例: |
文字列 |
friendlyName (必須) |
ビデオスキルの実装タイプを識別するための名前。この値は最大128文字までで、特殊文字や句読点を含めることはできません。注: ビデオスキル名と同じ値を入力しないでください。たとえば、ビデオスキルの名前が「ACME Media」の場合、フレンドリー名には「ACME Media」と入力しないでください。同じ名前を入力すると、エラーになります。名前に何らかの接頭辞を付けることをお勧めします(「TEST_ACME_Media」や「PROD_ACME_Media」など)。
例: |
文字列 |
manufacturerName (必須) |
デバイスのメーカーの名前。この値は最大128文字までです(Amazon側はこのフィールドを使用せず、開発者が入力した値もユーザーには表示されません。ただし、ビデオスキル名と同じ値を入力することはできません)。
例: |
文字列 |
capabilities配列
capabilities
配列は、interface
、type
、version
、supportOperations
の各プロパティをそれぞれに含むオブジェクトのリストです。たとえば、再生機能のサポートを宣言する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 に使用可能な値は、 Play 、Pause 、Stop 、StartOver 、Next 、Previous 、Rewind 、FastForward です。 |
Alexa.SeekController |
ビデオスキルは、Alexa.SeekController インターフェースのディレクティブをサポートできます。このインターフェースを使用すると、メディアタイムラインの特定の位置に移動できます。たとえば、「アレクサ、60秒早送りして」や「アレクサ、5分早戻しして」などです(アプリでメディアアイテムの早送りまたは早戻しのみが可能で、タイムラインの別のポイントまでシークできない場合は、代わりにPlaybackControllerインターフェースを実装します)。 |
Alexa.ChannelController |
ビデオスキルは、Alexa.ChannelControllerインターフェース のディレクティブをサポートできます。このインターフェースは、エンターテインメントデバイスのチャンネルを変更または進めるために使用されます。たとえば、「アレクサ、チャンネルをPBSに変えて」などです。 |
Alexa.KeypadController |
ビデオスキルは、Alexa.KeypadController インターフェースのディレクティブをサポートできます。このインターフェースは、左右または上下へのスクロールやフォーカスされているウィジェットの選択に使用されます。たとえば、「アレクサ、右にスクロールして」などです。 上記のコード例に従って、ビデオスキルでサポートしているキーのリストを指定します。キー値には、
UP 、DOWN 、LEFT 、RIGHT 、SELECT 、PAGE_UP 、PAGE_DOWN 、PAGE_LEFT 、PAGE_RIGHT 、INFO 、MORE があります。詳細については、この後のKeypadControllerインターフェースの機能の宣言を参照してください。KeypadController を使用するには、Alexa Client Libraryバージョン1.4.5以降が必要です。 |
Alexa.Launcher バージョン3.1以降のみ |
ビデオスキルは、バージョン3.1以降のAlexa.Launcher インターフェースのディレクティブをサポートできます。このインターフェースは、スキル内の任意の識別子やショートカットへの移動に使用されます。たとえば、「アレクサ、ウォッチリストに移動して」(ビデオスキルやアプリが起動中の場合)などです。レスポンスの例セクションを参考にして、ショートカットリストの構造を作成します。 |
KeypadControllerインターフェースの機能の宣言
アプリ内の音声ナビゲーションと選択で説明しているように、Fire TVではデフォルトで、アプリ内での音声によるスクロールと選択が可能です。Discovery
レスポンスでKeypadController
インターフェースの機能に対するサポートを指定しない場合、VSKはデフォルトのアプリ内音声ナビゲーションおよび選択機能にフォールバックします。
一方、Discovery
レスポンスでKeypadController
インターフェースの機能に対するサポートを指定した場合、デフォルトのアプリ内音声ナビゲーションおよび選択機能は無効になり、音声によるスクロールと選択は、Lambdaで受信するKeyStroke
ディレクティブへの応答を通じてのみ行われます。
KeypadController
のサポートを宣言する場合は、ビデオスキルでサポートするキーのリストを指定します。キー値には、
UP
、DOWN
、LEFT
、RIGHT
、SELECT
、PAGE_UP
、PAGE_DOWN
、PAGE_LEFT
、PAGE_RIGHT
、INFO
、MORE
があります。いずれかのキーコマンドのサポートを宣言すると、すべてのキーコマンドのアクションを管理していると見なされます。つまり、一部のキーコマンドのみをサポートして、それ以外をサポートしないという宣言はできません。
たとえば、
UP
を宣言しない場合でも、Alexaは、UP
値を含んだkeystroke
ペイロードを送信します。サポートされていないUP
機能を補うために、デフォルトのアプリ内音声ナビゲーションおよび選択機能が働くことはありません。