TemplateRuntimeインターフェース（v1.0）

TemplateRuntimeインターフェースは、GUIをサポートするAVS対応製品にビジュアルメタデータを提供します。これらの表示カードは、ユーザーの音声対話を説明または向上するために使用されます。メタデータは、JSONデータとして提供され、サポートされる各種デバイスの設計ガイドラインに準拠したテンプレートにバインドされる必要があります。

画面に特化した設計ガイドについては、UX設計の概要を参照してください。

データフロー
ビジュアルメタデータのレンダリング
機能API
RenderTemplateディレクティブ
RenderPlayerInfoディレクティブ
image構造体
- 画像サイズの仕様

データフロー

以下の図は、ビジュアルメタデータをAVS対応製品に配信する際のメッセージフローの概要を示しています。

ユーザーが「ウサイン・ボルトって誰?」と尋ねます。質問が製品にキャプチャされ、AVSにストリーミングされます。
AVSが以下の2つのディレクティブを返します。
- Alexa TTSを再生するようクライアントに指示するSpeakディレクティブ。
- ビジュアルメタデータ（この場合はウサイン・ボルトに関する情報）を表示するようクライアントに指示するRenderTemplateディレクティブ。
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ディレクティブを送信します。クライアントはこのメタデータをテンプレートにバインドし、エンドユーザーに対してレンダリングします。

重要： 「再生中」ビジュアルメタデータは、UX設計ガイドラインに記載された仕様に沿ってレンダリングする必要があります。

以下の例は、Amazon Musicコンテンツの再生を示しています。

注：ナビゲーションコントロールはコンテンツプロバイダーによって異なります。その他の情報については、UX設計の概要を参照してください。

サンプルメッセージ


{
  "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のコンテナに表示されます。

TemplateRuntimeインターフェース（v1.0）

データフロー

ビジュアルメタデータのレンダリング

機能API

RenderTemplateディレクティブ

BodyTemplate1

BodyTemplate2

ListTemplate1

WeatherTemplate

RenderPlayerInfoディレクティブ

image構造体

画像サイズの仕様

Alexa Skills Kit

Resources

Alexa Voice Service

AVS Resources

Connected Devices

Agreements

Blogs

Support