DIAL集成

DIAL集成 (Fire TV)

亚马逊Fire TV设备通过Whisperplay服务支持DIAL（发现和启动）协议。

关于DIAL
实现DIAL
Fire TV（第一屏幕）应用的更改
第二屏幕应用的更改
版本历史记录

关于DIAL

DIAL（发现并启动）协议（仅提供英文版）是一种开放协议，利用该协议，用户能够通过第二屏幕应用在另一台设备上发现和启动Fire TV应用。Fire TV和第二屏幕设备必须处于同一网络中。

DIAL不是一种比特流或屏幕镜像API，它能够利用第二屏幕设备上的应用发现和启动Fire TV应用（需要提供可选有效负载）。大多数情况下，您会同时拥有并实施第二屏幕应用（用于发送启动消息）和相应的Fire TV应用，即第一屏幕应用（用于接收该消息）。

有关开放DIAL协议，以及为应用注册DIAL服务的详细信息，请参阅DIAL网站。

实现DIAL

在最简单的情况下（仅启动），DIAL功能无需修改亚马逊Fire TV应用的代码，但需要修改应用的清单和资源，以指示对DIAL的支持，接受启动Intent。仅启动交互示例核心内容说明如下：

尽管如此，在大多数情况下，您仍会希望通过修改第一屏幕(Fire TV)应用的代码来处理DIAL启动参数（如深层链接），并为DIAL服务器的 additionalDataUrl提供反馈。

一般而言，若要利用DIAL的大多数功能、提供最佳客户体验，应遵循以下五个步骤：

在DIAL注册表中注册您的Fire TV应用。有关详细信息，请参阅关于注册表。
在Fire TV应用中，修改Android清单以支持DIAL。请参阅步骤A：修改您的Android清单。
在第一屏幕上的Fire TV应用中，将whisperplay.xml文件添加到应用的资源。请参阅步骤B：添加Whisperplay.xml文件。
在第一屏幕Fire TV应用代码中，处理启动Intent和额外信息。仅当第二屏幕应用在DIAL启动发送有效负载，和/或通过DIAL服务器从Fire TV应用请求额外的数据时，才需要执行此步骤。请参阅步骤C：处理启动Intent和additionalDataUrl。
在第二屏幕应用中实施DIAL协议，以在Fire TV上发现和启动应用。有关更多信息，特别是面向开发者的详细信息中的信息，请参阅DIAL网站。下面提供了第二屏幕应用更改的简短描述。

Fire TV（第一屏幕）应用的更改

以下部分列出了您必须对Fire TV应用进行的更改。

步骤A：修改您的Android清单

为了支持DIAL，您必须对Android清单(AndroidManifest.xml)进行两项更改：

向<application>中添加一个<meta-data>元素，以指示对DIAL的支持。
将DEFAULT类别添加到启动Intent中。

在清单的<application>部分中，添加以下<meta-data>元素：

<application ... >
    <meta-data android:name="whisperplay"  android:resource="@xml/whisperplay"/>
    ...
</application>

接下来，将DEFAULT Intent 类别（见下文XML）添加到主Activity的<intent-filter>元素中。如下文所述，您也可以为DIAL调用定义自定义启动操作。

    <activity android:name=".MainActivity"
              android:label="@string/title_activity_main" >
        ...
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />
            <category android:name="android.intent.category.LAUNCHER"/>
            <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>
    </activity>

步骤B：添加`Whisperplay.xml`文件

将名为whisperplay.xml的文件添加到应用的资源中，相应的目录为res/xml/。

重要须知： 自DIAL 2.2.1起，CORS授权模型已经得到多处增强。您必须在whisperplay.xml文件中迁移到新的<authorizedOrigins>字段（如下方代码所示）。原有的<authorizedDomain>机制格式已经更改，因此您可能需要审核并更新条目。

<?xml version="1.0" encoding="utf-8"?>
<whisperplay>
  <dial>
    <application>
    
      <!-- 注册DIAL注册表时的DIAL应用名称 -->
      <dialid>YourDialAppName</dialid>
      
      <!-- 已授权的客户端源组 -->
      <authorizedOrigins>
        <origin>https://www.example.com</origin>
        <origin>https://*.test.com</origin>
        <origin>package:com.example.dialapp</origin>
      </authorizedOrigins>
                 
      <!-- 启动应用Activity时可选用的Intent操作 -->
      <!-- 默认情况下，将尝试解决主启动器Activity -->
      <startAction>android.intent.action.MAIN</startAction>
      
      <!-- 第二屏幕应用发送DELETE命令时可选用的Intent操作
           （发送时间在您停止Activity之前）-->
      <!-- 默认情况下，DELETE中没有额外Intent -->
      <stopAction>YourDeleteAction</stopAction>
    
    </application>
  </dial>
</whisperplay>

通过<authorizedOrigins>实现CORS支持

请务必查看DIAL 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。相反，您可以按照以下方式来定义源组，以确保所有源都基于您的域：

<authorizedOrigins>
  <origin>https://*.amazon.com</origin>
  <origin>https://amazon.com</origin>
</authorizedOrigins>

重要须知： 强烈建议您将第一屏幕(<authorizedOrigins>)和第二屏幕(ORIGIN标头)都添加至DIAL应用，以充分利用其为客户提供的强大安全性。

步骤C：处理启动Intent和`additionalDataUrl`

如果应用接受DIAL有效负载（可通过DIAL启动请求传递给应用的信息），则该有效负载将通过密钥com.amazon.extra.DIAL_PARAM作为字符串Intent附加信息传送。第一屏幕应用用于POST可选附加信息的additionalDataUrl将在com.amazon.extra.DIAL_ADDITIONAL_DATA_URL密钥中作为另一字符串意图进行传送。此处可以认为第一屏幕应用可用于POST数据的additionalDataUrl形式为http://127.0.0.1:8009/apps/<YourDialAppName>/dial_data。

（可选）POST附加数据

重要提示：截至Android API 28 (Fire OS 7)，第一屏幕应用在发送additionalDataUrl时可能会因OS执行附加明文保护而遇到问题。建议您转至此处查看选项：https://developer.android.com/training/articles/security-config#CleartextTrafficPermitted。

如果要启用从第一屏幕应用返回至第二屏幕应用的初级双向通信或简单的反馈机制，则可以选用DIAL中的additionalDataUrl字段。对此，常见的使用方式为共享会话令牌或与第一屏幕应用状态相关的其他信息。可以将其视作第二屏幕应用在Fire TV未重启情况下可获取的第一屏幕应用的XML文档。为使Fire TV应用将信息成功发送至additionalDataUrl，相应源必须在whisperplay.xml的<authorizedOrigins>集合中进行注册。

请参阅DIAL 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规范，第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和设备描述请求的处理后，可以在UI中向用户显示找到的设备列表。

步骤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请求，其中包含作为资源名称的应用名称，以及启动参数（要向该应用发送的响应正文中的有效负载）。常见用例包括要在应用内播放的视频或音乐内容的链接。DIAL服务器通过指定的启动Intent启动应用，并在com.amazon.extra.DIAL_PARAM Intent附加信息中包含移动应用发送的可选有效负载。如果第二屏幕应用向第一屏幕应用请求额外的数据，则如DIAL协议中所指定，请求参数中的additionalDataUrl将在com.amazon.extra.DIAL_ADDITIONAL_DATA_URL Intent中发送到第一屏幕应用（请参阅步骤C：处理启动Intent和additionalDataUrl）。

第一屏幕应用负责处理响应第二屏幕应用发送的有效负载的操作。任何第二屏幕应用在其后发布的GET请求均可用于读取Fire TV第一屏幕应用发布的额外数据（例如，查看用于同步多个客户端的会话令牌）。

与任何应用开发一样，必须小心清理和关闭网络连接资源、处理异常、在非UI阻塞线程中启动线程，以及在网络操作失败时优雅退出。

版本历史记录

2021年4月5日： Fire TV设备上支持的DIAL服务器版本为v2.2.1。该版本优化了CORS授权模型，提供了新的<authorizedOrigins>标签。目前，Fire TV DIAL服务不支持远程应用安装和隐藏应用状态。
2020年8月1日： Fire TV设备上支持的DIAL服务器版本为v2.1。所有Fire TV设备都支持启动请求中的additionalDataUrl，并且Fire TV Edition都支持WoW/WoLAN功能。

Last updated: 2021年11月12日