TemplateRuntimeインターフェース(v1.0)

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

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

データフロー

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

データフローの図
クリックして拡大
  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 なしのディレクティブをすぐに実行します。
    • 新しいスレッド上で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 天気データを表示するよう設計されたテンプレート。 天気

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

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

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

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

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

パラメーター 説明
token Alexaで提供される不透明なトークンです。 文字列
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 文字列
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 オブジェクト
title.mainTitle タイトルです。 文字列
title.subTitle サブタイトルです。 文字列
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述のimage構造体を参照してください。 image構造体
textField 左寄せの本文テキスト。 文字列
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です。 文字列
dialogRequestId 特定のRecognizeイベントの応答として送信されるディレクティブの関連付けに使用する一意のIDです。 文字列

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

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

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

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

パラメーター 説明
token Alexaで提供される不透明なトークンです。 文字列
type テンプレートを識別します。この例では、typeBodyTemplate1に設定されています。 文字列
title タイトルやサブタイトルといったタイトル情報のキー/値ペアを含みます。実際のキー/値ペアはテンプレートによって異なります。 オブジェクト
title.mainTitle タイトルです。 文字列
title.subTitle サブタイトルです。 文字列
skillIcon メタデータを配信するスキルのアイコン/ロゴ。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります(またはnull値の場合があります)。image構造体には、urlsizewidthPixelsheightPixelsなどの情報が含まれます。詳細については、後述の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コンテンツの再生を示しています。

PlayerInfo
クリックして拡大

サンプルメッセージ


{
  "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_PAUSENEXTPREVIOUSです。 文字列
controls.enabled コントロールがクリック可能かどうかをクライアントに知らせます。ユーザーがクリック可能なコントロールの場合、値はtrueになります。 ブール値
controls.selected コントロールが選択された状態でレンダリングされることを示します。たとえば、ユーザーにお気に入りの楽曲がある場合、この楽曲が再生されると、お気に入りを表すコントロールのselected値はtrueになります。 ブール値

image構造体


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

パラメーター 説明
contentDescription 画像の説明です。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。 文字列
sources 同じ画像のソースのリストです。urlsizewidthPixelsheightPixelsが含まれる場合があります。このパラメーターはリストであり、1つまたは複数のソースの場合があることに注意してください。 リスト
sources[i].url 画像のURLです。JSONに必ず含まれます。 文字列
sources[i].darkBackgroundUrl おやすみモードアセットの画像URLです。これらの画像は、暗い背景での使用に最適化されています。これは、サービスからのオプションのパラメーターです。その他の情報については、こちらをクリックしてください。 文字列
sources[i].size 列挙値としての画像サイズです。コンテンツプロバイダーでは、このパラメーターはオプションであり、JSONに含まれない場合があります。widthPixelsheightPixelsのいずれか、または両方が指定されない場合、後述の仕様に従ってレンダリングしてください。 有効な値:X-SMALLSMALLMEDIUMLARGE、および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のコンテナに表示されます。