?
サポート

TemplateRuntime インターフェース



概要

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

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

データフロー

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

Data flow diagram.
クリックして拡大
  1. ユーザーが「ウサイン・ボルトって誰?」と尋ねます。質問が製品にキャプチャされ、AVSにストリーミングされます。
  2. AVSが以下の2つのディレクティブを返します。
    • Alexa TTSを再生するようクライアントに指示するSpeakディレクティブ。
    • ビジュアルメタデータ(この場合はウサイン・ボルトに関する情報)を表示するようクライアントに指示するRenderTemplateディレクティブ。
  3. Alexa TTSの再生が開始されます。
  4. 別スレッドで、RenderTemplateディレクティブ(可能な場合はSpeakディレクティブと並行して)がすぐにレンダリングされます。
  5. クライアントは、AVSにSpeechStartedイベントを送信することで、Alexa TTSの再生を開始したことを通知します。
  6. Alexa TTSの再生が完了すると、AVSにSpeechFinishedイベントを送信します。

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

ビジュアルメタデータのレンダリング時には、対話モデルで提供されるガイダンスに加えて、製品で以下のルールが実施される必要があります。

  • リクエストスレッド上の応答を読み取り、以下のようにディレクティブを解析します。
    • 新しいスレッド上でdialogRequestIdなしのディレクティブをすぐに実行します。
    • 新しいスレッド上でネームスペースTemplateRuntime内のディレクティブをすぐに実行します。
    • キュー内にdialogRequestIdのディレクティブを配置します。
  • キュー内のディレクティブは別のスレッド上で選択され、順に処理される必要があります。
  • ディレクティブと関連するRenderPlayerInfoディレクティブは同期される必要があります。RenderTemplateと異なり、ディレクティブは必ずしもすぐにレンダリングされる必要はありませんが、Playディレクティブの順序と一致する必要があります。たとえば、PlaybackNearlyFinishedの送信後に新しいPlayディレクティブとRenderPlayerInfoディレクティブを受信した場合は、キューに追加され、現在再生中のトラックの完了後に処理される必要があります。つまり、実装する表示カードで、再生、停止、一時停止といった再生の状態を認識する必要があるということです。

RenderTemplateディレクティブ

Renderディレクティブは、クライアントにユーザーリクエストに関連するビジュアルメタデータを表示するよう指示します。たとえば、ユーザーがAlexaに「Who is Usain Bolt?」と尋ねたとします。AVSは、Speakディレクティブの送信に加えて、ビジュアルメタデータとともにRenderディレクティブを送信します。クライアントはこのメタデータをテンプレートにバインドし、エンドユーザーに対してレンダリングします。

現在サポートされているテンプレートは、以下のとおりです。

説明 用途
BodyTemplate1 タイトル、サブタイトル、テキスト、スキルアイコンをサポートするテキストのみのテンプレート。 画像なしのWikipediaエントリー、ASKのシンプルなカード
BodyTemplate2 本文のテキストと1枚の画像をサポートするテンプレート。 画像ありのWikipediaエントリー。
ListTemplate1 リストとカレンダーのエントリーのテンプレート。 買い物リスト、To Doリスト、カレンダー。
WeatherTemplate 天気データを表示するよう設計されたテンプレート。 天気。

BodyTemplate1

BodyTemplate1は、テキストのみのビジュアルメタデータのレンダリングに使用されます。以下は、Wikipediaエントリーのサンプルです。

BodyTemplate1
クリックして拡大

サンプルメッセージ


{
  "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。 string
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブとの関連付けに使用される一意のID。 string

ペイロードのパラメーター

パラメーター 説明
token Alexaで提供される参照トークン。 string
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 string
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 object
title.mainTitle タイトル。 string
title.subTitle サブタイトル。 string
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述のimage構造体を参照してください。 image構造体
textField カードの本文テキスト。 string

BodyTemplate2

BodyTemplate2本文のテキストと1枚の画像をレンダリングするのに使用されます。以下は、Wikipediaエントリーのサンプルです。

BodyTemplate2
クリックして拡大

サンプルメッセージ


{
  "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。 string
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブとの関連付けに使用される一意のID。 string

ペイロードのパラメーター

パラメーター 説明
token Alexaで提供される参照トークン。 string
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 string
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 object
title.mainTitle タイトル。 string
title.subTitle サブタイトル。 string
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述のimage構造体を参照してください。 image構造体
textField 左寄せの本文テキスト。 string
image 右寄せの本文画像。 image構造体

ListTemplate1

ListTemplate1 は、リスト(To Doリスト、買い物リスト)やカレンダーエントリーのレンダリングに使用します。以下は、To Doリストとカレンダーエントリーのサンプルです。

To Doリスト

ListTemplate1
クリックして拡大

カレンダー

ListTemplate1
クリックして拡大

サンプルメッセージ


{
  "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。 string
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブとの関連付けに使用される一意のID。 string

ペイロードのパラメーター

パラメーター 説明
token Alexaで提供される参照トークン。 string
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 string
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 object
title.mainTitle タイトル。 string
title.subTitle サブタイトル。 string
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述のimage構造体を参照してください。 image構造体
listItems アイテムのリストまたはカレンダーのエントリー。 list
listItems.leftTextField 左寄せのテキストフィールドのコンテンツ。 string
listItems.rightTextField 右寄せのテキストフィールドのコンテンツ。 string

WeatherTemplate

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。 string
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブとの関連付けに使用される一意のID。 string

ペイロードのパラメーター

パラメーター 説明
token Alexaで提供される参照トークン。 string
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 string
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 object
title.mainTitle タイトル。 string
title.subTitle サブタイトル。 string
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述のimage構造体を参照してください。 image構造体
currentWeather リクエストされた日付の現在の気温。 string
description 現在の天気状況の説明。 string
currentWeatherIcon 現在の天気の画像。 image構造体
highTemperature 気温と画像のメタデータを含むオブジェクト。 object
hightemperature.value リクエストされた日付の最高気温。 string
hightemperature.arrow temperatureの横にレンダリングする矢印の画像。 image構造体
lowTemperature 気温と画像のメタデータを含むオブジェクト。 object
lowTemperature.value リクエストされた日付の最低気温。 string
lowTemperature.arrow temperatureの横にレンダリングする矢印の画像。 image構造体
weatherForecast リクエストされた日付からX日間の天気メタデータを示します。 list
weatherForecast.image 天気状況を表す画像。 image構造体
weatherForecast.day 曜日を示します。例: “Mon”“Tue”など。 string
weatherForecast.date 日付を示します。日付は、ABBR_MONTH_DAY形式で表されます。例: “Oct 22”など。 string
weatherForecast.highTemperature 関連する日付の最高気温を示します。 string
weatherForecast.lowTemperature 関連する日付の最低気温を示します。 string

RenderPlayerInfoディレクティブ

RenderPlayerInfoディレクティブは、クライアントにオーディオ再生(楽曲とオーディオブック)のユーザーリクエストに関連するビジュアルメタデータを表示するよう指示します。AVSは、Playディレクティブの送信に加えて、オーディオコンテンツプロバイダーに固有のビジュアルメタデータとともにRenderPlayerInfoディレクティブを送信します。クライアントはこのメタデータをテンプレートにバインドし、エンドユーザーに対してレンダリングします。

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

WeatherTemplate
クリックして拡大

サンプルメッセージ


{
  "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。 string
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブとの関連付けに使用される一意のID。 string

ペイロードのパラメーター

パラメーター 説明
audioItemId audioItemを識別します。 string
content タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 object
content.title タイトル。 string
content.titleSubtext1 1つ目のテキストフィールド。 string
content.titleSubtext2 2つ目のテキストフィールド。 string
content.header 1つ目のヘッダーテキストフィールド。 string
content.headerSubtext1 2つ目のヘッダーテキストフィールド。 string
content.mediaLengthInMilliseconds ストリーミングの再生時間(ミリ秒)。 long
content.art オーディオアイテムで提供される画像。 image構造体
content.provider コンテンツプロバイダーに関する情報が含まれます。 object
content.provider.name コンテンツプロバイダー名。 string
content.provider.logo コンテンツプロバイダーのロゴ。 image構造体
controls 画面上に表示する必要のあるボタンのリスト。 list
controls.type コントロールの種類を示します。有効な値: BUTTON string
controls.name コントロール名。配列に含まれるすべてのコントロールをレンダリングする必要があります。有効な値: PLAY_PAUSENEXTPREVIOUS string
controls.enabled コントロールがクリック可能かどうかをクライアントに知らせます。ユーザーがクリック可能なコントロールの場合、値はtrueになります。 ブール値

image構造体


{
  "contentDescription": "{{STRING}}",
  "sources": [
    {
      "url": "{{STRING}}",
      "darkBackgroundUrl": "{{STRING}}",
      "size": "{{STRING}}",
      "widthPixels": {{LONG}},
      "heightPixels": {{LONG}}
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

パラメーター 説明
contentDescription 画像の説明。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。 string
sources 同じ画像のソースのリスト。urlsizewidthPixelsheightPixelsが含まれる場合があります。このパラメーターはリストであり、1つまたは複数のソースの場合があることに注意してください。 list
sources[i].url 画像のURL。JSONに必ず含まれます。 string
sources[i].darkBackgroundUrl ナイトモード時の画像URL これらの画像は暗い背景に最適化されています。このパラメーターは**オプション**で利用することができます。詳細はこちらをご覧ください string
sources[i].size 列挙値としての画像サイズ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。widthPixelsheightPixelsのいずれか、または両方が指定されない場合、後述の仕様に従ってレンダリングしてください。有効な値は以下のとおりです。X-SMALLSMALLMEDIUMLARGEX-LARGE string
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のコンテナに表示されます。

その他のインターフェース

インターフェース 説明
SpeechRecognizer Alexa Voice Serviceのコアインターフェース。ユーザーの各発話はRecognizeイベントを利用します。
SpeechSynthesizer Alexa音声のインターフェース。
Alerts タイマーとアラームの設定、停止、削除のインターフェース。概念的な概要については、Alertsの概要を参照してください。
AudioPlayer オーディオ再生の管理と制御のインターフェース。概念的な概要については、AudioPlayerの概要を参照してください。
Notifications 通知インジケーターを表示するインターフェース。概念的な概要については、Notificationsの概要を参照してください。
PlaybackController ボタンアフォーダンスを介した再生キューのナビゲーションのインターフェース。
Speaker ミュート/ミュート解除を含む、デバイスまたはアプリの音量調整のインターフェース。
Settings ロケールなど、製品上でAlexa設定を管理するためのインターフェース。
System Alexaにクライアント情報を提供するためのインターフェース。

リソース