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

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

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

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

データフロー

以下の図は、ビジュアルメタデータを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

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}}"
    }
  }
}

ヘッダーのパラメーター

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

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}},
    }
  }
}

ヘッダーのパラメーター

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

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}}"
        },
        {
          ...
        }
      ]
    }
  }
}

ヘッダーのパラメーター

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

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}}"
        },
        {
          ...
        }
      ]
    }
  }
}

ヘッダーのパラメーター

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

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}}
        },
        {
          ...
        }
      ]
    }
  }
}

ヘッダーのパラメーター

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

image構造体

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

画像サイズの仕様

サポートされるsizeのそれぞれの列挙値を示します。