GetPlayableItemsMetadataディレクティブ(VSK Echo Show)
GetPlayableItems
に対するLambdaのレスポンスをAlexaが受信すると、すぐにVideoContentProvider APIがGetPlayableItemsMetadata
ディレクティブを送信します。このディレクティブは、GetPlayableItems
で返されたアイテムのメタデータを取得するためのフォローアップとして送信されます。
下の図は、Alexaディレクティブとそれに対するLambdaのレスポンスを示しています。
- GetPlayableItemsMetadataディレクティブの発話
- GetPlayableItemsMetadataディレクティブの処理
- GetPlayableItemsMetadataの例
- advertisingオブジェクト
- Lambdaレスポンス
- ペイロードの説明
GetPlayableItemsMetadataディレクティブの発話
GetPlayableItemsMetadata
ディレクティブの送信をAlexaに促すような発話はありません。このディレクティブは、GetPlayableItems
に対するLambdaのレスポンスを受信したAlexaがフォローアップとして送信します。
GetPlayableItemsMetadataディレクティブの処理
GetPlayableItemsMetadata
の目的は、リクエストされたアイテムの再生を開始するうえで必要なメタデータを取得することです。Alexaが正しい音声レスポンスを提供してコンテンツの再生を開始できるよう、Lambdaのレスポンスには基本的なメタデータを含める必要があります。
GetDisplayableItemsMetadata
と同様に、GetPlayableItemsMetadata
ディレクティブに含まれるのは、Alexaが(メディアを再生するために)メタデータを必要としているコンテンツのid
値だけです。検索結果の表示に必要となるメタデータは一切レスポンスに含めないでください。
GetPlayableItemsMetadataの例
GetPlayableItemsMetadata
ディレクティブの例を次に示します。この例では、recordingId://provider1.dvr.rp.1234-2345-63434-asdf
を値に持つmediaIdentifier
のメタデータをAlexaがリクエストしています。返すのはGetPlayableItemsMetadata
ディレクティブで指定されたエンティティid
値のメタデータのみです。
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
"name": "GetPlayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"payload": {
"locale": "ja-JP",
"mediaIdentifier": {
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
}
}
チャンネル変更に使用されるGetPlayableItemsMetadata
ディレクティブもほぼ同じですが、mediaIdentifier
のid
が異なる場合があります。その例を次に示します。
"payload": {
"locale": "ja-JP",
"mediaIdentifier": {
"id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
}
}
この例では、特定のメディアタイトルではなく、チャンネルにid
が関連付けられています。
advertisingオブジェクト
advertising
オブジェクトは、ユーザーの広告IDと、インタレストベース広告の受信に関する設定を提供します。Alexaはビデオスキルへのリクエストにadvertising
オブジェクトを追加して、広告を配信することを宣言します。詳しくは、Alexa広告IDについての説明を参照してください。
Alexaの広告IDを取得するには、そのスキルが広告を配信することを表明し、プライバシーポリシーを公開して、スキルの再認定を申請する必要があります。
advertisingオブジェクトの構造
プロパティ | 説明 | 型 | 必須・任意 |
---|---|---|---|
advertisingId |
ユーザーによるリセットが可能な一意の識別子であり、OpenRTB API仕様のifa 属性に該当します。バージョン4 UUID文字列の形式で表され、ダッシュで区切られます(8-4-4-4-12)。例: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367 |
文字列 | 必須 |
limitAdTracking |
ユーザーがインタレストベース広告の受信を希望しているかどうかを示します。ユーザーがインタレストベース広告をオプトアウトしている場合はtrue に設定されます。limitAdTracking プロパティは、OpenRTB API仕様のlmt 属性に該当します。 |
ブール型 | 必須 |
設定例
以下は、ユーザーがインタレストベース広告を受信しないように選択した場合の設定例です。
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": true
}
"advertising": {
"advertisingId": "00000000-0000-0000-0000-00000000",
"limitAdTracking": true
}
以下は、ユーザーがインタレストベース広告の受信を選択した場合の設定例です。
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
広告配信に必要なビデオスキルAPI
再生中にインストリーム広告が表示されるようにするため、以下のAlexaビデオスキルAPIでは、GetPlayableItemsMetadata
ペイロードにrequestContext
オブジェクトを追加しています。
このオブジェクトには、広告配信に関するユーザーの設定を示す広告コンテキストが含まれます。advertisingオブジェクトを使用できるように、該当するAPIでスキルのコードを更新してください。これらのAPIの詳細については、Alexaから送信されるディレクティブを参照してください。
リクエストごとにadvertisingオブジェクトを使用するようにスキルを設計します。コードで、advertisingId
にアクセスする前に、limitAdTracking
フラグを検証するコードを挿入します。limitAdTracking == true
の場合、ユーザーの選択を尊重してトラッキングを無効にする必要があります。
スキルセッション中またはスキルセッション後に、ユーザーが自分のIDをリセットして、インタレストベース広告の受信に関する設定を変更する可能性があるため、広告のプロパティをキャッシュに格納しないでください。Alexaは、スキルへの次のリクエストで最新の値を送信します。ユーザーから明示的な同意を得ていない限り、以前のadvertisingId
や、以前のadvertisingId
に割り当てられている値に新しいadvertisingId
を関連付けないでください。また、ユーザーから明示的な同意を得ていない限り、個人データをadvertisingId
に関連付けないでください。
ユーザーがインタレストベース広告を受信しないことを選択した場合、advertisingId
を分析で使用することは可能ですが、トラッキングとインタレストベース広告を無効にする必要があります。リクエストによっては、advertisingオブジェクトが含まれない可能性があります。advertisingId
を使用する場合と、使用しない場合を想定してスキルを設計してください。ユーザーのオプトアウトの選択に従う必要があります。
GetPlayableItemsMetadataリクエストの例
以下は、advertisingオブジェクトを使用したGetPlayableItemsMetadata
リクエストの例です。
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
"name": "GetPlayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"payload": {
"locale": "ja-JP",
"mediaIdentifier": {
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
},
"requestContext": {
"advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
}
}
}
}
Lambdaレスポンス
Lambdaのレスポンス(GetPlayableItemsMetadataResponse
)には、再生に必要となるメタデータ情報と、ビデオの再生前に成功のプロンプトを提供するために必要となるメタデータ情報のみを含める必要があります。GetPlayableItemsMetadataResponse
とGetDisplayableItemsMetadataResponse
はよく似ていますが、GetPlayableItemsMetadataResponse
にはplaybackContextToken
が存在します。このトークンには、Alexaがウェブプレーヤーに渡す識別子が含まれています。playbackContextToken
は、対象のメディアに関して開発者が決定する識別子です。
AlexaがplaybackContextToken
をウェブプレーヤーに送信すると、その識別子がウェブプレーヤーで再生URLに変換されます。このプロセスについては、手順4: ウェブプレーヤーでメディア再生URLを取得する方法を理解するで説明しています。前出のコード例で、playbackContextToken
が文字列化されたオブジェクト(streamUrl
パラメーターとtitle
パラメーターから成るキーと値のペア)になっているのは、この形式がサンプルウェブプレーヤーで想定されているためです。
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
この識別子を処理するウェブプレーヤーのコーディングによっては、単純に文字列などの形式を使用することもあります。
ON_DEMAND
(VOD)メディアのレスポンスは、LIVE
(リニア)メディアのレスポンスとは異なります。contentType
が異なるだけでなく、LIVE
のレスポンスにはnetworkDetails
が含まれます。
レスポンスの例:オンデマンドのテレビ番組
ビデオオンデマンド(VOD)コンテンツのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "ビッグバン・セオリー",
"contentType": "ON_DEMAND",
"series": {
"seasonNumber": "1",
"episodeNumber": "2",
"seriesName": "ビッグバン・セオリー",
"episodeName": "ターミネーターキャメロンVSオタクの法則"
},
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"absoluteViewingPositionMilliseconds": 1232340
}
]
}
}
}
レスポンスの例:ライブの映画
ライブコンテンツのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"networkDetails": [
{
"channel": {
"callSign": "PBS",
"affiliateCallSign": "KCTS9"
},
"channelMetadata": {
"name": "代替チャンネル名"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"start": "2018-01-24T00:00:00Z",
"end": "2018-01-24T02:30:00Z"
}
]
}
]
}
]
}
}
}
レスポンスの例:チャンネル変更のシナリオ
チャンネル変更のシナリオでのレスポンスの例を次に示します。
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetPlayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "インターステラー",
"contentType": "LIVE",
"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"<ビデオタイトル>\"}",
"parentalControl": {
"pinControl": "REQUIRED"
},
"networkDetails": [
{
"channel": {
"callSign": "PBS",
"affiliateCallSign": "KCTS9"
},
"channelMetadata": {
"name": "代替チャンネル名"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"start": "2018-01-24T00:00:00Z",
"end": "2018-01-24T02:30:00Z"
}
]
}
]
}
]
}
}
}
ペイロードの説明
次の表は、GetPlayableItemsMetadataResponse
レスポンスのペイロードについて説明しています。
フィールド | 説明 | データ型 |
---|---|---|
searchResults (必須) |
検索結果のリスト。 | リスト |
name (必須) |
ビデオの名前。再生されるビデオについてのプロンプトをユーザーに提供する目的で使用します。たとえば、「インターステラーはこちらです」などです。 例: |
文字列 |
(省略可能) |
|
|
contentType (必須) |
例: |
列挙型 |
playbackContextToken (必須) |
その後の識別のためにエンティティをシステムに逆マッピングするためのトークン。開発者側で逆マッピングによってエンティティを識別できれば、どのような文字列識別子を送信しても構いません。このトークンはAlexaからは認識できず、再生目的でデバイスに送信されます。メタデータ情報を取得したときと同じメディア識別子が再生に必要であれば、それを使用して構いません。または、再生に必要な追加情報を含んだ別の文字列をシリアル化して使用することもできます。 注: サンプルウェブプレーヤーを使用する場合、 |
不透明型の文字列 |
parentalControl (必須) |
ユーザーとビデオに基づくペアレンタルコントロール情報。 |
オブジェクト |
pinControl (必須) |
このフィールドは、このビデオのユーザーに対して、設定に基づくペアレンタルコントロールが必要であるかどうかを示します。次の2つの値を取る列挙値です。
例: |
列挙型 |
networkDetails (省略可能) |
番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組( |
リスト |
channel (省略可能) |
ビデオを放送しているチャンネルに関する情報。 |
オブジェクト |
callSign (channel)(省略可能) |
PBSなどのコールサインでチャンネルを指定します。
例: |
文字列 |
affiliateCallSign (channel)(省略可能) |
KCTS9といった地方系列局のコールサインでチャンネルを指定します。
例: |
文字列 |
channelMetadata (省略可能) |
指定されたチャンネルの追加情報を指定します。 |
オブジェクト |
name (channelMetadata)(省略可能) |
「FOX」など、チャンネルを識別する別の値。 | 文字列 |
airingDetails (省略可能) |
このオブジェクトには、コンテンツがいつ放送されるかの情報が含まれます。 |
リスト |
isLiveBroadcast (省略可能) |
このコンテンツがリアルタイムで放送されているかどうか。NFLフットボールの試合中継や、アカデミー賞、エミー賞のような授賞式など、リアルタイムで放送されるライブイベントの場合は、 実際に放送される時刻よりも前に撮影されたコンテンツの場合は、 例: |
ブール型 |
start (省略可能) |
タイムウィンドウの開始時刻。 例: |
ISO 8601形式の文字列 |
end (省略可能) |
タイムウィンドウの終了時刻。 例: |
ISO 8601形式の文字列 |
networkDetails (省略可能) |
番組を放送しているネットワークについての情報。たとえば、「ビッグバン・セオリー」の新しいエピソードであればCBS、サッカーの生中継であればESPNといった放送局の情報です。オンデマンドコンテンツの場合は、たとえばAmazonプライム・ビデオで配信される「ゲーム・オブ・スローンズ」であれば、制作局のHBOとなります。結果アイテムがチャンネルのライブ番組( |
リスト |
series (省略可能) |
シリーズに関するメタデータ(このアイテムがシリーズの一部である場合)。この情報は、テレビ番組にのみ設定してください。ここに値が設定されている場合は、その情報を使用してユーザーにプロンプトが提供されます(例:「『ビッグバン・セオリー』のシーズン1、エピソード4はこちらです」)。 |
オブジェクト |
seasonNumber (series)(省略可能) |
ビデオのシーズン番号。 例: |
文字列 |
episodeNumber (series)(省略可能) |
ビデオのエピソード番号。 例: |
文字列 |
episodeName (series)(省略可能) |
エピソード名。 例: |
文字列 |
seriesName (series)省略可能 |
シリーズの名前です。 | 文字列 |
absoluteViewingPositionMilliseconds (必須) |
ユーザーの視聴履歴に基づいたビデオの進行状況オフセット(ミリ秒)。ユーザーに視聴履歴がある場合、このフィールドが表すオフセットは0より大きくなります。結果アイテムで進行状況バーを表示して、ユーザーが以前どこまで視聴したかを示す目的で使用されます。 例: |
長整数 |