TemplateRuntimeインターフェース(v1.0)
TemplateRuntimeインターフェースは、GUIをサポートするAVS対応製品にビジュアルメタデータを提供します。これらの表示カードは、ユーザーの音声対話を説明または向上するために使用されます。メタデータは、JSONデータとして提供され、サポートされる各種デバイスの設計ガイドラインに準拠したテンプレートにバインドされる必要があります。
画面に特化した設計ガイドについては、UX設計の概要を参照してください。
データフロー
以下の図は、ビジュアルメタデータをAVS対応製品に配信する際のメッセージフローの概要を示しています。

- ユーザーが「ウサイン・ボルトって誰?」と尋ねます。質問が製品にキャプチャされ、AVSにストリーミングされます。
- AVSが以下の2つのディレクティブを返します。
- Alexa TTSを再生するようクライアントに指示する
Speak
ディレクティブ。 - ビジュアルメタデータ(この場合はウサイン・ボルトに関する情報)を表示するようクライアントに指示する
RenderTemplate
ディレクティブ。
- Alexa TTSを再生するようクライアントに指示する
- Alexa TTSの再生が開始されます。
- 別スレッドで、
RenderTemplate
ディレクティブ(可能な場合はSpeak
ディレクティブと並行して)がすぐにレンダリングされます。 - クライアントは、AVSに
SpeechStarted
イベントを送信することで、Alexa TTSの再生を開始したことを通知します。 - Alexa TTSの再生が完了すると、AVSに
SpeechFinished
イベントを送信します。
ビジュアルメタデータのレンダリング
ビジュアルメタデータのレンダリング時には、対話モデルで提供されるガイダンスに加えて、製品で以下のルールが実施される必要があります。
- リクエストスレッド上の応答を読み取り、以下のようにディレクティブを解析します。
- 新しいスレッド上で
dialogRequestId
なしのディレクティブをすぐに実行します。 - 新しいスレッド上で
RenderTemplate
ディレクティブをすぐに実行します。 - キュー内に
dialogRequestId
ありのディレクティブを配置します。
- 新しいスレッド上で
- キュー内のディレクティブは別のスレッド上で選択され、順に処理される必要があります。
Play
ディレクティブと関連するRenderPlayerInfo
ディレクティブは同期される必要があります。RenderTemplate
と異なり、ディレクティブは必ずしもすぐにレンダリングされる必要はありませんが、Play
ディレクティブの順序と一致する必要があります。たとえば、PlaybackNearlyFinished
の送信後に新しいPlay
ディレクティブとRenderPlayerInfo
ディレクティブを受信した場合は、キューに追加され、現在再生中のトラックの完了後に処理される必要があります。つまり、実装する表示カードで、再生、停止、一時停止といった再生の状態を認識する必要があるということです。
機能API
AudioPlayerインターフェースのバージョン1.0を使用するには、機能APIの呼び出し内で宣言する必要があります。詳細については、機能APIを参照してください。
オブジェクトのサンプル
{ "type": "AlexaInterface", "interface": "TemplateRuntime", "version": "1.0" }
RenderTemplateディレクティブ
Render
ディレクティブは、クライアントにユーザーリクエストに関連するビジュアルメタデータを表示するよう指示します。たとえば、ユーザーがAlexaに「ウサイン・ボルトって誰?」と尋ねたとします。AVSは、Speak
ディレクティブの送信に加えて、ビジュアルメタデータとともにRender
ディレクティブを送信します。クライアントはこのメタデータをテンプレートにバインドし、エンドユーザーに対してレンダリングします。
現在サポートされているテンプレートは、以下のとおりです。
型 | 説明 | 用途 |
---|---|---|
BodyTemplate1 | タイトル、サブタイトル、テキスト、スキルアイコンをサポートするテキストのみのテンプレート。 | 画像なしのWikipediaエントリー、ASKのシンプルなカード。 |
BodyTemplate2 | 本文のテキストと1枚の画像をサポートするテンプレート。 | 画像ありのWikipediaエントリー。 |
ListTemplate1 | リストとカレンダーのエントリーのテンプレート。 | 買い物リスト、To Doリスト、カレンダー。 |
WeatherTemplate | 天気データを表示するよう設計されたテンプレート。 | 天気 |
type
には、クライアントでレンダリングする必要があるコンテンツ固有の一意のペイロードパラメーターがあります。BodyTemplate1
BodyTemplate1
は、テキストのみのビジュアルメタデータのレンダリングに使用されます。以下は、Wikipediaエントリーのサンプルです。

サンプルメッセージ
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "BodyTemplate1", "title": { "mainTitle": "{{STRING}}", "subTitle": "{{STRING}}" }, "skillIcon": {{IMAGE STRUCTURE}}, "textField": "{{STRING}}" } } }
ヘッダーのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
messageId | 特定のメッセージを表すのに使用する一意のIDです。 | 文字列 |
dialogRequestId | 特定のRecognize イベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 |
文字列 |
ペイロードのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
token | Alexaで提供される不透明なトークンです。 | 文字列 |
type | テンプレートを識別します。この例では、type はBodyTemplate1 に設定されています。 |
文字列 |
title | タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 | オブジェクト |
title.mainTitle | タイトルです。 | 文字列 |
title.subTitle | サブタイトルです。 | 文字列 |
skillIcon | メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull 値の場合があります)。image構造体には、url 、size 、widthPixels 、heightPixels などの情報が含まれます。詳細については、後述のimage構造体を参照してください。 |
image構造体 |
textField | カードの本文テキスト。 | 文字列 |
BodyTemplate2
BodyTemplate2
本文のテキストと1枚の画像をレンダリングするのに使用されます。以下は、Wikipediaエントリーのサンプルです。

サンプルメッセージ
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "BodyTemplate2", "title": { "mainTitle": "{{STRING}}", "subTitle": "{{STRING}}" }, "skillIcon": {{IMAGE_STRUCTURE}}, "textField": "{{STRING}}", "image": {{IMAGE_STRUCTURE}}, } } }
ヘッダーのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
messageId | 特定のメッセージを表すのに使用する一意のIDです。 | 文字列 |
dialogRequestId | 特定のRecognize イベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 |
文字列 |
ペイロードのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
token | Alexaで提供される不透明なトークンです。 | 文字列 |
type | テンプレートを識別します。この例では、type はBodyTemplate1 に設定されています。 |
文字列 |
title | タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 | オブジェクト |
title.mainTitle | タイトルです。 | 文字列 |
title.subTitle | サブタイトルです。 | 文字列 |
skillIcon | メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull 値の場合があります)。image構造体には、url 、size 、widthPixels 、heightPixels などの情報が含まれます。詳細については、後述のimage構造体を参照してください。 |
image構造体 |
textField | 左寄せの本文テキスト。 | 文字列 |
image | 右寄せの本文画像。 | image構造体 |
ListTemplate1
ListTemplate1
は、リスト(To Doリスト、買い物リスト)やカレンダーエントリーのレンダリングに使用します。以下は、To Doリストとカレンダーエントリーのサンプルです。
To Doリスト

カレンダー

サンプルメッセージ
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "ListTemplate1", "title": { "mainTitle": "{{STRING}}", "subTitle": "{{STRING}}" }, "skillIcon": {{IMAGE_STRUCTURE}}, "listItems": [ { "leftTextField": "{{STRING}}", "rightTextField": "{{STRING}}" }, { "leftTextField": "{{STRING}}", "rightTextField": "{{STRING}}" }, { ... } ] } } }
ヘッダーのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
messageId | 特定のメッセージを表すのに使用する一意のIDです。 | 文字列 |
dialogRequestId | 特定のRecognize イベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 |
文字列 |
ペイロードのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
token | Alexaで提供される不透明なトークンです。 | 文字列 |
type | テンプレートを識別します。この例では、type はBodyTemplate1 に設定されています。 |
文字列 |
title | タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 | オブジェクト |
title.mainTitle | タイトルです。 | 文字列 |
title.subTitle | サブタイトルです。 | 文字列 |
skillIcon | メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull 値の場合があります)。image構造体には、url 、size 、widthPixels 、heightPixels などの情報が含まれます。詳細については、後述のimage構造体を参照してください。 |
image構造体 |
listItems | アイテムのリストまたはカレンダーのエントリー。 | リスト |
listItems.leftTextField | 左寄せのテキストフィールドのコンテンツ。 | 文字列 |
listItems.rightTextField | 右寄せのテキストフィールドのコンテンツ。 | 文字列 |
WeatherTemplate
WeatherTemplate
天気予報をレンダリングするためのセマンティックテンプレート。

サンプルメッセージ
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderTemplate", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "token": "{{STRING}}", "type": "WeatherTemplate", "title": { "mainTitle": "{{STRING}}", "subTitle": "{{STRING}}" }, "skillIcon": {{IMAGE_STRUCTURE}}, "currentWeather": "{{STRING}}", "description": "{{STRING}}", "currentWeatherIcon": {{IMAGE_STRUCTURE}}, "highTemperature": { "value": "{{STRING}}", "arrow": {{IMAGE_STRUCTURE}} }, "lowTemperature": { "value": "{{STRING}}", "arrow": {{IMAGE_STRUCTURE}} }, "weatherForecast": [ { "image": {{IMAGE_STRUCTURE}}, "day": "{{STRING}}", "date": "{{STRING}}", "highTemperature": "{{STRING}}", "lowTemperature": "{{STRING}}" }, { "image": {{IMAGE_STRUCTURE}}, "day": "{{STRING}}", "date": "{{STRING}}", "highTemperature": "{{STRING}}", "lowTemperature": "{{STRING}}" }, { ... } ] } } }
ヘッダーのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
messageId | 特定のメッセージを表すのに使用する一意のIDです。 | 文字列 |
dialogRequestId | 特定のRecognize イベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 |
文字列 |
ペイロードのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
token | Alexaで提供される不透明なトークンです。 | 文字列 |
type | テンプレートを識別します。この例では、type はBodyTemplate1 に設定されています。 |
文字列 |
title | タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 | オブジェクト |
title.mainTitle | タイトルです。 | 文字列 |
title.subTitle | サブタイトルです。 | 文字列 |
skillIcon | メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull 値の場合があります)。image構造体には、url 、size 、widthPixels 、heightPixels などの情報が含まれます。詳細については、後述のimage構造体を参照してください。 |
image構造体 |
currentWeather | リクエストされた日付の現在の気温。 | 文字列 |
description | 現在の天気状況の説明。 | 文字列 |
currentWeatherIcon | 現在の天気の画像。 | image構造体 |
highTemperature | 気温と画像のメタデータを含むオブジェクト。 | オブジェクト |
hightemperature.value | リクエストされた日付の最高気温。 | 文字列 |
hightemperature.arrow | temperature の横にレンダリングする矢印の画像。 |
image構造体 |
lowTemperature | 気温と画像のメタデータを含むオブジェクト。 | オブジェクト |
lowTemperature.value | リクエストされた日付の最低気温。 | 文字列 |
lowTemperature.arrow | temperature の横にレンダリングする矢印の画像。 |
image構造体 |
weatherForecast | リクエストされた日付からX日間の天気メタデータを示します。 | リスト |
weatherForecast.image | 天気状況を表す画像。 | image構造体 |
weatherForecast.day | 曜日を示します。例:"Mon"や"Tue"など。 | 文字列 |
weatherForecast.date | 日付を示します。日付は、ABBR_MONTH_DAY形式で表されます。例:“Oct 22”など。 | 文字列 |
weatherForecast.highTemperature | 関連する日付の最高気温を示します。 | 文字列 |
weatherForecast.lowTemperature | 関連する日付の最低気温を示します。 | 文字列 |
RenderPlayerInfoディレクティブ
RenderPlayerInfo
ディレクティブは、クライアントにオーディオ再生のユーザーリクエストに関連するビジュアルメタデータを表示するよう指示します。AVSは、Play
ディレクティブの送信に加えて、オーディオコンテンツプロバイダーに固有のビジュアルメタデータとともにRenderPlayerInfo
ディレクティブを送信します。クライアントはこのメタデータをテンプレートにバインドし、エンドユーザーに対してレンダリングします。
以下の例は、Amazon Musicコンテンツの再生を示しています。

サンプルメッセージ
{ "directive": { "header": { "namespace": "TemplateRuntime", "name": "RenderPlayerInfo", "messageId": "{{STRING}}", "dialogRequestId": "{{STRING}}" }, "payload": { "audioItemId": "{{STRING}}", "content": { "title": "{{STRING}}", "titleSubtext1": "{{STRING}}", "titleSubtext2": "{{STRING}}", "header": "{{STRING}}", "headerSubtext1": "{{STRING}}", "mediaLengthInMilliseconds": {{LONG}}, "art": {{IMAGE_STRUCTURE}}, "provider": { "name": "{{STRING}}", "logo": {{IMAGE_STRUCTURE}} } }, "controls": [ { "type": "BUTTON", "name": "{{STRING}}", "enabled": {{BOOLEAN}}, "selected": {{BOOLEAN}} }, { "type": "BUTTON", "name": "{{STRING}}", "enabled": {{BOOLEAN}}, "selected": {{BOOLEAN}} }, { ... } ] } } }
ヘッダーのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
messageId | 特定のメッセージを表すのに使用する一意のIDです。 | 文字列 |
dialogRequestId | 特定のRecognize イベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 |
文字列 |
ペイロードのパラメーター
パラメーター | 説明 | 型 |
---|---|---|
audioItemId | audioItemを識別します。このパラメーターは、指定されたビジュアルメタデータをPlay ディレクティブに関連付けるのに使用します。 |
文字列 |
content | タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 | オブジェクト |
content.title | タイトルです。 | 文字列 |
content.titleSubtext1 | 1つ目のテキストフィールドです。 | 文字列 |
content.titleSubtext2 | 2つ目のテキストフィールドです。 | 文字列 |
content.header | 1つ目のヘッダーテキストフィールドです。 | 文字列 |
content.headerSubtext1 | 2つ目のヘッダーテキストフィールドです。 | 文字列 |
content.mediaLengthInMilliseconds | ストリーミングの再生時間(ミリ秒)です。 | long |
content.art | オーディオアイテムで提供される画像です。 | image構造体 |
content.provider | コンテンツプロバイダーに関する情報が含まれます。 | オブジェクト |
content.provider.name | コンテンツプロバイダー名です。 | 文字列 |
content.provider.logo | コンテンツプロバイダーのロゴです。 | image構造体 |
controls | 画面上に表示する必要のあるボタンのリストです。 | リスト |
controls.type | コントロールの種類を示します。有効な値は、BUTTON です。 |
文字列 |
controls.name | コントロール名です。配列に含まれるすべてのコントロールをレンダリングする必要があります。有効な値:PLAY_PAUSE 、NEXT 、PREVIOUS です。 |
文字列 |
controls.enabled | コントロールがクリック可能かどうかをクライアントに知らせます。ユーザーがクリック可能なコントロールの場合、値はtrue になります。 |
ブール値 |
controls.selected | コントロールが選択された状態でレンダリングされることを示します。たとえば、ユーザーにお気に入りの楽曲がある場合、この楽曲が再生されると、お気に入りを表すコントロールのselected 値はtrue になります。 |
ブール値 |
image構造体
source.url
のみです。その他のフィールドを送信するかどうかはコンテンツプロバイダーの任意ですが、クライアントではこれらのフィールドが存在する場合に処理できるようにしておく必要があります。注: sources
は画像のリストで、同じ画像の1つまたは複数のソースである可能性があります。複数のソースが指定されるという保証はありません。{ "contentDescription": "{{STRING}}", "sources": [ { "url": "{{STRING}}", "darkBackgroundUrl": "{{STRING}}", "size": "{{STRING}}", "widthPixels": {{LONG}}, "heightPixels": {{LONG}} }, { ... }, { ... } ] }
パラメーター | 説明 | 型 |
---|---|---|
contentDescription | 画像の説明です。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。 | 文字列 |
sources | 同じ画像のソースのリストです。url 、size 、widthPixels 、heightPixels が含まれる場合があります。このパラメーターはリストであり、1つまたは複数のソースの場合があることに注意してください。 |
リスト |
sources[i].url | 画像のURLです。JSONに必ず含まれます。 | 文字列 |
sources[i].darkBackgroundUrl | おやすみモードアセットの画像URLです。これらの画像は、暗い背景での使用に最適化されています。これは、サービスからのオプションのパラメーターです。その他の情報については、こちらをクリックしてください。 | 文字列 |
sources[i].size | 列挙値としての画像サイズです。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。widthPixels 、heightPixels のいずれか、または両方が指定されない場合、後述の仕様に従ってレンダリングしてください。 有効な値:X-SMALL 、SMALL 、MEDIUM 、LARGE 、およびX-LARGE です。 |
文字列 |
sources[i].widthPixels | 画像の幅(ピクセル)です。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。 | long |
sources[i].heightPixels | 画像の高さ(ピクセル)です。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。 | long |
画像サイズの仕様
サポートされるsize
のそれぞれの列挙値を示します。
値 | 説明 |
---|---|
X-SMALL | x-smallのコンテナに表示されます。 |
SMALL | smallのコンテナに表示されます。 |
MEDIUM | mediumのコンテナに表示されます。 |
LARGE | largeのコンテナに表示されます。 |
X-LARGE | x-largeのコンテナに表示されます。 |