使用DIAL
DIAL（发现并启动）协议（仅提供英文版）是一种开放协议，利用该协议，用户能够通过第二屏幕应用在另一台设备上发现和启动Fire TV应用。Fire TV和第二屏幕设备必须处于同一网络中。
请注意，DIAL不是一种比特流或屏幕镜像API，它能够利用第二屏幕设备上的应用发现和启动Fire TV应用（需要提供可选有效负载）。大多数情况下，您会同时拥有并实施第二屏幕应用（用于发送启动消息）和相应的Fire TV应用，即第一屏幕应用（用于接收该消息）。
有关开放DIAL协议，以及为应用注册DIAL服务的详细信息，请参阅DIAL网站。
启用DIAL
更新您的清单
要允许DIAL检测应用程序/程序包是否支持Vega上的DIAL，必须将以下内容添加到manifest.toml文件中：
[[extras]]
key = "dial_id"
value = "<DIAL ID>"
[[extras]]
key = "dial_launch_component"
value = "<要使用pkg URL启动的组件名称>"
dial_id是您在DIAL注册表中选择并注册的应用名称，该注册表位于https://www.dial-multiscreen.org/dial-registries/about-the-registry（仅提供英文版）。- 这与用于Fire OS型实现的whisperplay.xml文件中的“dialid”相同。
dial_launch_component是DIAL启动的程序包中的交互式组件。当DIAL发送启动URI时，其格式为：*pkg://<dial_launch_component>?<DIAL POST请求的有效负载>&DIAL_ADDITIONAL_DATA_URL=http://127.0.0.1:8009/apps/<Dial ID>/dial_data
（可选）通过<authorizedOrigins>实现CORS支持
请务必查看DIAL spec v2.2.1，第6.6节（仅提供英文版），了解更多关于CORS授权和客户端源额外要求的详细信息。亚马逊实现要求应用必须在第一屏幕应用的Whisperplay.xml文件中指定一组已授权的CORS源（请参阅上文示例）。允许包括"*"字符的通配符格式，可匹配零到多个字符.请注意，某些不安全的URI方案（如file:、http:和ftp:等）无论在授权列表中显示与否，都已明确禁止。
注意不要指定过度开放的授权源。例如，如果您想要授权https://test.amazon.com和https://amazon.com，请勿将*amazon.com指定为授权源。该源过度开放，可能会在不经意间对意外的源进行授权，如https://evilamazon.com。相反，您可以按照以下方式来定义源组，以确保所有源都基于您的域：
要支持CORS，请将以下内容添加到manifest.toml中：
[[extras]]
key = "dial_origins"
value = "<URL/程序包1>,<URL/程序包2>"
<authorizedOrigins>) 和第二屏幕 (ORIGIN标头) 都添加至DIAL应用，以充分利用其为客户提供的强大安全性。处理启动和additionalDataUrl
如果应用接受DIAL有效负载（可通过DIAL启动请求传递给您的应用的信息），则该有效负载将作为启动URI中的参数提供。第一屏幕应用用于POST可选附加信息的additionalDataUrl将作为启动URI中的另一个参数提供。这将采用以下格式：pkg://<dial_launch_component>?<DIAL POST请求的有效负载>&DIAL_ADDITIONAL_DATA_URL=http://127.0.0.1:8009/apps/<Dial ID>/dial_data。
可以假设第一屏幕应用可用于POST数据的additionalDataUrl形式为http://127.0.0.1:8009/apps/<DIAL ID>/dial_data。
（可选）POST附加数据
如果要启用从第一屏幕应用返回至第二屏幕应用的初级双向通信或简单的反馈机制，则可以选用DIAL中的additionalDataUrl字段。对此，常见的使用方式为共享会话令牌或与第一屏幕应用状态相关的其他信息。可以将其视作第二屏幕应用在Fire TV未重启情况下可获取的第一屏幕应用的XML文档。为使Fire TV应用将信息成功发送至additionalDataUrl，相应源必须在manifest.toml的dial_origins中另行注册。
有关第一屏幕和第二屏幕应用所需和提供的附加数据机制的具体格式，请参阅DIAL docs v2.2.1，第6.3节（仅提供英文版）。
第二屏幕应用的更改
以下部分列出了您需要对第二屏幕应用进行的更改。
步骤A： 在支持DIAL的设备上实现发现服务
在第二屏幕应用（即DIAL客户端）上，实施DIAL协议的客户端规范。DIAL发现基于UPnP/SSDP规范构建。在后台活动或线程中，发送UDP M-SEARCH请求，其搜索目标为“urn:dial-multiscreen-org:service:dial:1”。
Fire TV会响应M-SEARCH请求，响应中包含唯一服务名称(USN)、用于获取设备描述的位置/URL以及搜索目标。此外，可能还会包含一个WAKEUP标头，表明当前能够使用远程唤醒将电视从暂停模式中唤醒（请参阅DIAL 2.2.1 spec，第7节 [仅提供英文版] 了解详情）。由于可以从设备接收多个M-SEARCH响应，因此必须基于USN提取唯一设备。
以下是请求和响应示例。
M-SEARCH请求示例：
M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN: "ssdp:discover"
MX: 10
ST: urn:dial-multiscreen-org:service:dial:1
USER-AGENT: OS/version product/version
M-SEARCH响应示例：
HTTP/1.1 200 OK
USN: uuid:7b077d4c-a222-5b72-0000-0000182185c7::urn:dial-multiscreen-org:service:dial:1
CACHE-CONTROL: max-age=1800
EXT:
ST: urn:dial-multiscreen-org:service:dial:1
LOCATION: http://192.168.1.141:60000/upnp/dev/7b077d4c-a222-5b72-0000-0000182185c7/desc
SERVER: Linux/4.4.120 UPnP/1.0 Cling/2.0
接下来，为了获取有关设备的更多信息，请使用M-SEARCH响应中的设备描述位置/URL来发送HTTP请求。响应在其标头中包含一个名为Application-URL的重要属性，称为DIAL REST服务。此Application-URL随后用于与设备上的应用进行交互。从响应正文中提取并存储设备易记型名称、型号名称和制造商，以便向用户显示这些值，这样做会对您很有帮助。
完成对M-SEARCH和设备描述请求的处理后，可以在用户界面中向用户显示找到的设备列表。
步骤B： 获取应用状态
在设备上启动应用之前，先检测设备应用的状态（也可以选择读取additionalData来加载第一屏幕应用的缓存信息）将大有裨益。为了获取应用的状态，在用户选择要启动应用的设备后，向DIAL REST服务发送HTTP GET请求，其中将应用名称作为资源名称。请求中的应用名称必须与DIAL注册表中注册的名称（以及Whisperplay.xml文件中规定的名称）匹配。
如果无法识别应用名称且/或应用未安装，则会返回HTTP 404错误。第二屏幕设备可向用户提供一个选项，用于在第一屏幕设备上安装来自亚马逊应用商店的应用，但此功能超出了DIAL协议的范围。
如果HTTP请求成功，则DIAL服务器会通过HTTP 200 OK响应进行回应。响应正文包含的一个属性可表明应用的状态——hidden、 stopped、running或installable（请注意，Fire TV DIAL服务器目前不支持installable和hidden）以及第一屏幕应用此前发送至additionalDataUrl的任何XML格式的additionalData。
步骤C： 启动应用
接下来，启动第一屏幕应用时只需向DIAL REST服务发送HTTP POST请求，其中包含作为资源名称的应用名称，以及启动参数（要向该应用发送的响应正文中的有效负载）。常见用例包括要在应用内播放的视频或音乐内容的链接。
第一屏幕应用负责处理响应第二屏幕应用发送的有效负载的操作。任何第二屏幕应用在其后发布的GET请求均可用于读取Fire TV第一屏幕应用发布的额外数据（例如，查看用于同步多个客户端的会话令牌）。
与任何应用开发一样，必须小心清理和关闭网络连接资源、处理异常、在非用户界面阻塞线程中启动线程，以及在网络操作失败时优雅退出。
Last updated: 2025年9月30日
