Developer Console
Sign In
Sign In
Developer Console

DIAL Integration

Amazon Fire TV devices support the DIAL (Discovery-and-Launch) protocol through the Whisperplay service.

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 (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:

  1. 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.

  2. Register your Fire TV app with the DIAL registry. See About the Registry for details.

  3. 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 com.amazon.extra.DIAL_PARAM.

  4. In your Fire TV app, modify the Android manifest to support DIAL. See Modify your Android Manifest.

  5. 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 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 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: 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 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), stopped, 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 <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>
        </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 com.amazon.extra.DIAL_PARAM.