开发人员控制台

DIAL集成(Fire TV)


DIAL集成(Fire TV)

Amazon Fire TV设备通过Whisperplay服务支持DIAL(发现和启动)协议。

关于DIAL

Amazon Fire TV设备通过Whisperplay服务支持DIAL(发现并启动)协议。DIAL是一种开放协议,利用该协议,用户能够通过第二屏幕应用在另一台设备上发现和启动Fire TV应用。Fire TV和第二屏幕设备必须处于同一网络中。

请注意,DIAL不会投射API,也不会生成API的镜像。DIAL仅允许第二屏幕设备上的应用查找和启动Fire TV上的应用。大多数情况下,您会同时实施第二屏幕应用(用于发送启动消息)和相应的Fire TV应用,即第一屏幕应用(用于接收该消息)。

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

实现DIAL

DIAL功能无需修改Amazon Fire TV应用的代码,但需要修改应用的清单和资源,以指示对DIAL的支持,接受启动意图(intents)。

要使Fire TV和第二屏幕应用支持DIAL,需要执行五个步骤:

  1. 在第二屏幕应用中实施DIAL协议,以在Fire TV上发现和启动应用。有关更多信息,特别是面向开发者的详细信息中的信息,请参阅DIAL网站。下面提供了第二屏幕应用更改的简短描述。

  2. 在DIAL注册表中注册您的Fire TV应用。有关详细信息,请参阅关于注册表

  3. 在Fire TV应用中,处理启动意图。仅当第二屏幕应用在DIAL启动请求有效负载中发送附加信息,和/或通过DIAL服务器从Fire TV应用请求额外的数据时,才需要执行此步骤。请参阅处理启动意图

  4. 在Fire TV应用中,修改Android清单以支持DIAL。请参阅修改Android清单

  5. 在Fire TV应用中,将Whisperplay.xml文件添加到应用的资源。请参阅添加Whisperplay.xml文件

第二屏幕应用的更改

以下部分列出了您需要对第二屏幕应用进行的更改。

步骤A: 在支持DIAL的设备上实现发现服务

在第二屏幕应用(即DIAL客户端)上,实施DIAL协议的客户端规范。DIAL基于uPnP规范构建。在后台活动或线程中,发送UDP M-SEARCH请求,其搜索目标为“urn:dial-multiscreen-org:service:dial:1”

Fire TV会响应M-SEARCH请求,响应中包含唯一服务名称(USN)、用于获取设备描述的位置/URL以及搜索目标。由于可以从设备接收多个UDP响应,因此必须基于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: 获取应用状态

在设备上启动应用之前,了解应用在设备上的状态非常重要。为了获取应用的状态,在用户选择要启动应用的设备后,向DIAL REST服务发送HTTP GET请求,其中将应用名称作为资源名称。请求中的应用名称必须与DIAL注册表中注册的名称匹配。

如果无法识别应用名称且应用未安装,则会返回HTTP 404错误。第二屏幕设备可向用户提供一个选项,用于在第一屏幕设备上安装来自亚马逊应用商店的应用,但此功能超出了DIAL协议的范围。

如果HTTP请求成功,则DIAL服务器会通过HTTP 200 OK响应进行回应。响应正文包含的一个属性可表明应用的状态——hiddenstoppedrunninginstallable(请注意,Fire TV DIAL服务器目前不支持t installablehidden)。

步骤C: 启动应用

接下来,启动第一屏幕应用时只需向DIAL REST服务发送HTTP POST请求,其中包含作为资源名称的应用名称、可选请求参数,以及要向该应用发送的响应正文中的有效负载。常见用例包括要在应用内播放的视频或音乐内容的链接。DIAL服务器启动应用,并在com.amazon.extra.DIAL_PARAM意图中传递移动应用发送的有效负载。如果第二屏幕应用向第一屏幕应用请求额外的数据,则如DIAL协议中所指定,请求参数中的additionalDataURL将在com.amazon.extra.DIAL_ADDITIONAL_DATA_URL意图中发送到第一屏幕应用。为使Fire TV应用成功调用additionalDataURL,必须在Whisperplay.xml的additionalDataURL标签中注册应用提供商的域名。

第一屏幕应用负责处理响应第二屏幕应用发送的有效负载及additionalDataURL的操作。

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

您Fire TV应用的更改

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

步骤A: 修改您的Android清单

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

  • <application>中添加一个<meta-data>元素,以指示对Whisperplay和DIAL的支持。
  • DEFAULT类别添加到启动意图中。

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

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

接下来,将DEFAULT意图类别添加到主活动的<intent-filter>元素中:

    <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/。该文件的内容应如下所示,其中DialAppName是应用在DIAL注册表中的名称:

<whisperplay>
    <dial>
        <application>
            <dialid>DialAppName</dialid>
            <startAction>android.intent.action.MAIN</startAction>
            <! Optional intent to be invoked when DELETE command is sent from second-screen app -->
            <**stopAction**>YourDeleteActionIntent</**stopAction**>

            <authorizedDomain>.yourdomain.com</authorizedDomain>
        </application>
    </dial>
</whisperplay>

步骤C: 处理启动意图

如果应用接受DIAL有效负载(可通过DIAL启动请求传递给应用的信息),则该有效负载将通过值com.amazon.extra.DIAL_PARAM作为意图附加信息传送。第二屏幕应用作为启动请求参数发送的AdditionalDataURL将通过值com.amazon.extra.DIAL_ADDITIONAL_DATA_URL作为意图额外信息传送。

版本历史记录

截至2020年8月1日,Fire TV设备上的DIAL服务器版本为v2.1。所有Fire TV设备都支持启动请求中的AdditionalDataURL,并且所有Fire TV Edition都支持WoW/WoLAN功能。