Using DIAL

DIAL (Discovery-and-Launch) protocol 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 bit-streaming or screen mirroring API, it enables apps on a second-screen device to find and launch apps on a Fire TV (with an optional payload). In most cases, you own and 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.

Enabling DIAL

Update your manifest

To allow DIAL to detect that an application/package supports DIAL on Vega you must add the following to the manifest.toml file:

[[extras]]
key = "dial_id"
value = "<DIAL ID>"

[[extras]]
key = "dial_launch_component"
value = "<Component name to launch using pkg URL>"

• The dial_id is the app name that you have chosen and registered in the dial registry located at https://www.dial-multiscreen.org/dial-registries/about-the-registry.
  • This is the same as the "dialid" in the whisperplay.xml file that was used for Fire OS-based implementations.
• The dial_launch_component is the interactive component in your package that DIAL launches. When DIAL sends a launch URI, it is in the format: * pkg://<dial_launch_component>?<Payload of DIAL POST Request>&DIAL_ADDITIONAL_DATA_URL=http://127.0.0.1:8009/apps/<Dial ID>/dial_data

(Optional) CORS support via <authorizedOrigins>

Please be sure to review the DIAL spec v2.2.1, section 6.6 for more details on the additional requirements for CORS authorization and client origins. The Amazon implementation requires your app to specify a collection of authorized CORS origins within your first-screen app’s whisperplay.xml file (see example above). The format allows for wildcard matches using the "*" character which will match zero-to-many characters. Note that certain insecure URI schemes (including file: http:, ftp: and others) are explicitly forbidden regardless of whether they appear in your authorized list.

Take care when specifying your authorized origins to not be overly permissive. For example, if you want to authorize both https://test.amazon.com and https://amazon.com DO NOT specify your authorized origin as *amazon.com. This is overly permissive and may inadvertently authorize an unexpected origin such as https://evilamazon.com. Instead, you could define the collection as shown below which ensures all origins are based on the domain you own:

To support CORS, add the following to the manifest.toml:

[[extras]]
key = "dial_origins"
value = "<URL/Package 1>,<URL/Package 2>"

Handle Launching and additionalDataUrl

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 a parameter in the launch URI. The additionalDataUrl used by your first-screen app to optionally POST additional information is delivered as another parameter in the launch URI. This will be in the format: pkg://<dial_launch_component>?<Payload of DIAL POST Request>&DIAL_ADDITIONAL_DATA_URL=http://127.0.0.1:8009/apps/<Dial ID>/dial_data.

It is safe to assume that the additionalDataUrl will be in the form http://127.0.0.1:8009/apps/<DIAL ID>/dial_data to which your first-screen app may POST data.

(Optional) POST Additional Data

If you would like to enable very rudimentary two-way communication or a simple feedback mechanism from your first-screen app back to your second-screen app, you may opt to use DIAL's additionalDataUrl field. A common use case for this is to share a session token or some other information tied to your first-screen application’s state. You can think of this as an XML document that your first-screen application makes available to your second-screen app that persists as long as the Fire TV is not rebooted. In order for the Fire TV app to successfully POST to the additionalDataUrl, the corresponding origin must be registered in the dial_origins extra in manifest.toml.

Refer to the DIAL docs v2.2.1, section 6.3 on the specific formats expected and provided by the additional data mechanism for both first- and second-screen apps.

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 discovery is built on top of the UPnP/SSDP 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. Additionally, there may be an extra WAKEUP header included indicating the TV currently has the capability to be woken from suspend mode using magic packets (refer to the DIAL 2.2.1 spec, section 7 for more details). Since it is possible to receive multiple M-SEARCH 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 useful to detect the state of the app on the device (and optionally read additionalData to load cached information from your first-screen app). 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 (and specified in your whisperplay.xml file).

If the app name is not recognized and/or 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), and any XML-formatted additionalData that was previously POSTed to the additionalDataUrl by the first-screen app.

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, and optional payload in the request body to send to the app as a launch parameter. A common use case could be a link to video or music content to play within the app.

The first-screen app is responsible for handling actions in response to the payload sent from the second-screen app. Subsequent GET requests issued by any second-screen app can be used to read any additional data that was POSTed by the first-screen Fire TV app (e.g. a viewing session token to synchronize multiple clients).

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.

---

Last updated: Sep 30, 2025