DIAL Integration (Fire TV)
Amazon Fire TV devices support the DIAL (Discovery-and-Launch) protocol through the Whisperplay service.
- About DIAL
- Implementing DIAL
- Changes to the Second-screen App
- Changes to Your Fire TV App
- Version History
About DIAL
Amazon Fire TV devices support the DIAL (Discovery-and-Launch) protocol through the Whisperplay service. DIAL is an open protocol that enables your Fire TV app to be discoverable and launchable from another device via a second-screen app. Both Fire TV and the second-screen device must be on the same network.
Note that DIAL is not a casting or mirroring API. DIAL only enables apps on a second-screen device to find and launch apps on a Fire TV. In most cases, you implement both the second-screen app (to send a launch message), and the corresponding Fire TV app, aka first-screen app (to receive that message).
For more information about the open DIAL protocol and to register your app with the DIAL service, see the DIAL website.
Implementing DIAL
DIAL functionality does not require any changes to your Amazon Fire TV app's code, but you do need to modify your app's manifest and resources to indicate support for DIAL and to accept launch intents.
There are five steps to implementing DIAL support for your Fire TV and second-screen apps:
-
In your second-screen app, implement the DIAL protocol to discover and launch apps on Fire TV. See the DIAL website for more information, and specifically the information in Details for Developers. A short description of changes to the second-screen app is provided below.
-
Register your Fire TV app with the DIAL registry. See About the Registry for details.
-
In your Fire TV app, handle launch intents. This step is only necessary if your second-screen app sends additional information in the DIAL launch request payload and/or is requesting additional data from the Fire TV app, through the DIAL Server. See Handle Launch Intents.
-
In your Fire TV app, modify the Android manifest to support DIAL. See Modify your Android Manifest.
-
In your Fire TV app, add a
Whisperplay.xml
file to your app's resources. See Add the Whisperplay.xml File.
Changes to the Second-screen App
The following sections list changes you need to make to the second-screen app.
Step A: Implement the DIAL-enabled device discovery service
On the second-screen app (aka the DIAL client), implement the client specification of the DIAL protocol. DIAL is built on top of the uPnP specification. In a background activity or thread, send a UDP M-SEARCH request with the search target as "urn:dial-multiscreen-org:service:dial:1"
.
Fire TV responds to the M-SEARCH request with a response containing a unique service name (USN), the location/URL to obtain a device description, and the search target. Because it is possible to receive multiple UDP responses from the device, you must extract unique devices based on the USN.
The following is a sample request and response.
Sample M-SEARCH Request:
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
Sample M-SEARCH Response:
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
Next, to obtain more information about the device, send an HTTP request using the device description location URL in the M-SEARCH response. The response contains an important attribute in its header called Application-URL
, referred to as the DIAL REST Service. This Application-URL
is subsequently used to interact with the app on the device. From the response body, it is useful to extract and store the device-friendly name, model name, and manufacturer to display these values to the user.
After the processing of the M-SEARCH and device descriptions requests is complete, the list of devices found can be presented to the user in the UI.
Step B: Get App Status
Before launching the app on the device, it is important to know the state of the app on the device. To get the state of the app, once the user selects a device to launch the app on, send an HTTP GET request to the DIAL REST service with the app name as the resource name. The app name in the request must match the name registered in the DIAL registry.
If the app name is not recognized and the app is not installed, an HTTP 404 error is returned. The user could be presented the option on the second-screen device to install the app on the first-screen device from the Appstore, but this functionality is out of scope for the DIAL protocol.
If the HTTP request is successful, the DIAL server responds with an HTTP 200 OK response. The response body contains an attribute that informs the state of the app — hidden
, stopped
, running
, or is installable
(note that installable
and hidden
are not currently supported by the Fire TV DIAL server).
Step C: Launch the App
Next, launching the first-screen app is as simple as sending an HTTP POST request to the DIAL REST Service with the app name as the resource name, optional request parameter, and payload in the response body to send to the app. A common use case could be a link to the video or music content to play within the app. The DIAL server launches the app and passes the payload sent by the mobile app in the com.amazon.extra.DIAL_PARAM
intent. If the second-screen app requests additional data from the first-screen app, the additionalDataURL
from the request parameter as specified in DIAL protocol is sent in the com.amazon.extra.DIAL_ADDITIONAL_DATA_URL
intent to the first-screen app. In order for the Fire TV app to successfully call the additionalDataURL
, the application provider’s domain name must be registered in the <authorizedDomain>
tag in Whisperplay.xml.
The first-screen app is responsible for handling actions in response to the payload and additionalDataURL
sent from the second-screen app.
As with any app development, care must be taken to clean up and close network connection resources, handle exceptions, launch threads in non-UI blocking threads, and fail gracefully when network operations fail.
Changes to Your Fire TV App
The following sections list changes you must make to your Fire TV app.
Step A: Modify your Android Manifest
There are two changes you must make to your Android manifest (AndroidManifest.xml
) to support DIAL:
- Add a
<meta-data>
element to<application>
that indicates support for Whisperplay and DIAL. - Add the
DEFAULT
category to your launch intent.
In the <application>
portion of your manifest, add the following <meta-data>
element:
<application ... >
<meta-data android:name="whisperplay" android:resource="@xml/whisperplay"/>
...
</application>
Next, add the DEFAULT
intent category to your primary (main) activity's <intent-filter>
element:
<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>
Step B: Add the Whisperplay.xml File
Add a file called Whisperplay.xml
to your app's resources, in the res/xml/
directory. The contents of the file should look as follows, where DialAppName
is the name of your app in the DIAL registry:
<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>
<authorizedDomain>
field to your Whisperplay.xml
file as shown in the code above. Note that the domain is a suffix match, so subdomain.yourdomain.com
would also be accepted.Step C: Handle Launch Intents
If your app accepts a DIAL payload (information that can be passed to your app via the DIAL launch request), that payload will be delivered as an Intent extra with the value com.amazon.extra.DIAL_PARAM
. The AdditionalDataURL
sent as a launch request parameter from the second-screen app is delivered as an Intent extra with the value com.amazon.extra.DIAL_ADDITIONAL_DATA_URL
.
Version History
As of Aug 1, 2020, the version of the DIAL Server on Fire TV devices is v2.1. AdditionalDataURL
in the launch request is supported on all Fire TV devices and the WoW/WoLAN feature is supported on all Fire TV Editions.
Last updated: Oct 30, 2020