TemplateRuntime接口对具有屏显与图形介面的TVS设备提供了视觉元数据。这些元数据中的展示卡片 (display cards) 是用来描述或增强用户的语音交互体验的。这些元数据会以结构化的JSON形式提供，并且其结构应该以如下所述的各个模版形式相同。

数据流

下图以比较高的层次说明了精灵服务是如何向接入精灵的设备下发视觉元数据的信息流：

1. 用户问：「谁是马云?」其音频语音会被设备捕捉并传送给TVS。
2. TVS返回两个指令：
   • 一个告知客户端应该播放TTS的 Speak 指令。
   • 一个用来要求客户端用来展示视觉元数据的 TemplateRuntime。在此例中，就是马云的信息。
3. 精灵服务的TTS开始播放。
4. 客户端立刻渲染 RenderTemplate 指令中的数据 (如果可以的话，与 Speak 在不同线程中执行)。
5. 客户端上报 SpeechStarted 事件来告知TVS已经开始播放TTS。
6. 当TTS播报完毕时，向TVS上报 SpeechFinished 事件。

渲染视觉元数据

除了在交互模型中所提供的规范外，你的产品在渲染视觉元数据时也必须遵守以下准则：

• 与发送请求的线程中读取回复并解析指令：
  • 必须立刻在一个新的线程中执行不带有 dialogRequestId 的指令。
  • 必须立刻在一个新的线程中执行 RenderTemplate 指令。
  • 将带有 dialogRequestId 的指令放置到指令队列之中。
• 队列中的指令应该由另一个线程取出并依顺序处理。
• Play 指令及与其关连的 RenderPlayerInfo 指令的处理必须同步。与 RenderTemplate 不同，RenderTemplate 指令不需要总是立刻进行渲染。例如，在发送一个 PlaybackNearlyFinished 事件之后，如果你收到了新的 Play 指令和 RenderPlayerInfo 指令，则两者都必须加入队列中，且需要在当前音频播放完毕之后处理。这也代表展示卡片的实现必须要对播控状态有所感知，例如正在播放、停止或暂停等等。

RenderTemplate指令

以下是目前支持的templates：

BodyTemplate1

BodyTemplate1 用于渲染纯文本的可视数据。下面是一个百科的示例:

Sample Message

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

Header参数

Payload参数

BodyTemplate2

BodyTemplate2 用于渲染主体文本和单个图像。

Sample Message

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

Header参数

Payload参数

ListTemplate1

ListTemplate1 用于渲染列表(待办事项列表、购物列表)和日历条目。

Sample Message

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

Header参数

Payload参数

WeatherTemplate

WeatherTemplate 是一个渲染天气预报的模板.

Sample Message

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

Header参数

Payload参数

LocalSearchListTemplate1

ExtCommonExceptionTemplate用于查询周边地址的信息的渲染

Sample Message

{
	"directive": {
		"header": {
			"namespace": "TemplateRuntime",
			"name": "RenderTemplate",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"payload": {
			"token": "{{STRING}}",
			"type": "LocalSearchListTemplate1",
			"listItems": [{
				"rightPrimaryTextField": "{{STRING}}",
				"leftTextField": "{{STRING}}",
				"rightSecondaryTextField": "{{STRING}}",
				"onClickAction": [{
					"directive": {
						"header": {
							"namespace": "Navigation",
							"name": "SetDestination"
						},
						"payload": {
							"metadata": {
								"rating": "{{STRING}}",
								"cost": "{{STRING}}",
								"phoneNumber": "{{STRING}}"
							},
							"destination": {
								"name": "{{STRING}}",
								"coordinate": {
									"longitudeInDegrees": {{DOUBLE}},
									"latitudeInDegrees": {{DOUBLE}}
								},
								"singleLineDisplayAddress": "{{STRING}}",
								"province": "{{STRING}}",
								"city": "{{STRING}}",
								"county": "{{STRING}}"
							},
						}
					}
				}]
			}],
			"title": {
				"mainTitle": "{{STRING}}",
				"subTitle": "{{STRING}}"
			}
		}
	}
}

Header参数

Payload参数

onClickAction参数

RenderPlayerInfo指令

AVS官方文档链结: https://developer.amazon.com/de/docs/alexa-voice-service/templateruntime.html#renderplayerinfo

RenderPlayerInfo 指令要求客户端展示关于某个media item的相关视觉元数据，例如一首歌或一个播放清单。除了发送Play指令外，TVS还将发送带有特定于音频内容提供者的可视元数据的RenderPlayerInfo指令，您的客户端会将其绑定到模板并为最终用户呈现。

Sample Message

{
  "directive": {
    "header": {
      "namespace": "TemplateRuntime",
      "name": "RenderPlayerInfo",
      "messageId": "{{STRING}}",
      "dialogRequestId": "{{STRING}}"
    },
    "payload": {
      "audioItemId": "{{STRING}}",
      "content": {
        "title": "{{STRING}}",
        "titleSubtext1": "{{STRING}}",
        "titleSubtext2": "{{STRING}}",
        "header": "{{STRING}}",
        "mediaLengthInMilliseconds": {{LONG}},   
        "art": {
		  "sources":[
		    {
			"url": "{{STRING}}"
			}
		  ]
		},     
        "provider": {
          "name": "{{STRING}}",
          "logo": {{IMAGE_STRUCTURE}}
        }                
      }
      "controls": [
        // This array includes all controls that must be
        // rendered on-screen.
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          ...
        }
      ]
    }
  }
}

Header参数

Payload参数

Control参数

控制项与事件的对映

当用户与屏显上的控制项进行交互时，与控制项对应的事件必须使用 PlaybackController 接口发送给精灵服务。下表是控制项与 PlaybackController接口中对应的事件：

Image Structure

{
  "sources": [
    {
      "url": "{{STRING}}",
	   "darkBackgroundUrl": "{{STRING}}"
    },
    {
      ...
    },
    {
      ...
    }
  ]
}

通用按钮（扩展）

除了RenderPlayerInfo里面的按钮控件之外，TVS提供通用的按钮控件，TemplateRuntime接口返回的渲染指令可能包含一个或多个控件，客户端需要渲染这些控件，完成必要的前端交互功能，并需上报控件事件给GeneralController接口。

示例代码：

"controls": [
        // This array includes all controls that must be
        // rendered on-screen.
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          "type": "{{STRING}}",
          "name": "{{STRING}}",
          "enabled": {{BOOLEAN}},
          "selected": {{BOOLEAN}}
        },
        {
          ...
        }
      ]

控制项与事件的对映

当用户与屏显上的控制项进行交互时，与控制项对应的事件必须使用 GeneralController 接口发送给精灵服务。下表是控制项与 GeneralController接口中对应的事件：

FAQ