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
DIAL is an open protocol that enables your Fire TV app to be discoverable and launchable from another device via a second screen app. 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 (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.
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 DIAL launch intent payloads. This step is only necessary if your second screen app sends an intent payload. That payload is delivered as an Intent extra with the value
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.xmlfile 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 uPnP specification. In a background activity or thread, send a UDP M-SEARCH request with the search target as
Fire TV responds to the M-SEARCH request with a response containing a unique service name (USN), the location/URL to obtain 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 USN.
The following are a sample request and response.
Sample M-SEARCH Request:
M-SEARCH * HTTP/1.1 HOST: 184.108.40.206: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 a 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 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 the 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, a HTTP 404 error is returned. The user could be presented the option on second-screen device to install the app on the first-screen device from the Appstore, but this functionality is out of scope of the DIAL protocol.
If the HTTP request is successful, the DIAL server responds with a HTTP 200 OK response. The response body contains an attribute that informs the state of the app —
hidden (since v2.1),
running, or is
installable (note that
installable is not currently supported by Fire TV DIAL server).
Step C: Launch the App
Next, launching the first-screen app is as simple as sending a HTTP POST request to the DIAL REST Service with app name as the resource name and any additional 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. The first-screen app is responsible for handling actions in response to the payload 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
<application>that indicates support for Whisperplay and DIAL.
- Add the
DEFAULTcategory to your launch intent.
<application> portion of your manifest, add the following
<application ... > <meta-data android:name="whisperplay" android:resource="@xml/whisperplay"/> ... </application>
Next, add the
DEFAULT intent category to your primary (main) activity's
<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> </application> </dial> </whisperplay>
Step C: DIAL Payload Intent
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