Developer Console
Sign In
Sign In
Developer Console

DIAL Integration (Fire TV)

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

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

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

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