Alexa.MediaDetailsNavigator interface sends DisplayDetails directives to your Lambda to provide information about the item. The MediaDetailsNavigator interface builds on the UI state report described in UIController. If you’re already implementing UIController, it makes sense to also implement MediaDetailsNavigator to handle these scenarios.
Detailed Explanation
TheAlexa.MediaDetailsNavigator interface provides more information about a specific media item. For example, the customer might say, “Alexa, show more details about Iron Man” or “Alexa, show details about number three.” Or with the element in focus (selected), the user could simply say “Alexa, show details.” This request isn’t a navigation instruction (hence not handled by UIController) nor is it a media playback request (hence not handled by SearchAndPlay) but is instead a request for more detail about a particular “entity.”
In the Alexa discourse, entities refer to the types of items that exist. The primary entities related to Fire TV include Video, Episode, and Event. When you configure your support for MediaDetailsNavigator, you indicate which entities your app supports. This semantic detail allows Alexa to better understand the customer’s requests in context with what’s on your app’s screen.
MediaDetailsNavigator leverages the same UI report described in UIController. You send in a UI state report that describes the elements shown in your screen (updated each time your screen changes). When customers make requests for more detail about items on the screen, Alexa sends your Lambda a MediaDetailsNavigator directive named DisplayDetails that includes specific element names and details from your UI state.
Supported Utterances
Alexa sends aDisplayDetails directive (namespace is MediaDetailsNavigator) to your Lambda when users ask for more detail about a specific item. Sample utterances include the following:
- “Alexa, show details for Breaking Bad”
- “Alexa, show details for comedy movies”
- “Alexa, show details for Bosch”
- “Alexa, show details for number 2”
- “Alexa, show details” [with entity in focus]
- “Alexa, show details for this” [entity in focus]
Sending UI State Reports
Follow same process as outlined inUIController for sending the UI state report.
VSK-Enabled Apps
You need to add support forMediaDetailsNavigator in the Alexa Client Library. In the initializeAlexaClient method, add getMediaDetailsNavigatorCapability to the list of supportedCapabilities.
VSK-Enabled Devices
See Sending UI State Reports. However, in Step 3 - Indicate that Properties Are Proactively Reported During Discovery, indicate support forMediaDetailsNavigator as follows:
MediaDetailsNavigator, include the object shown in the capabilities array. This includes providing a configurations object that contains an entityTypes array. In this array, you list the types of entities your app supports. Although there are many different entity types for Alexa, only two entity types are supported for the MediaDetailsNavigator interface: Video and App.
| Entity | Description |
|---|---|
Video | Video represents the identifying data for the piece of video content. |
App | App represents the explicit app name specified by the user in utterance. |
UI State Report Example and Schema, Payload Definitions, Data Structures
The UI state report you send is described in theUIController documentation in the section titled UI State Report Example and Schema. Similarly, payload definitions for the UI State report are described in Payload Definitions, and the data structures for the UI report are also described in Data Structures — all in the UIController docs. MediaDetailsNavigator builds on the functionality you already implemented in UIController.
DisplayDetails Directive Example
When the customer makes a request as described in Supported Utterances, theMediaDetailsNavigator interface sends a directive with the name DisplayDetails to your Lambda. The following is an example directive:
Payload Definitions
Thepayload for the DisplayDetails directive depends on the type of entity returned. In the previous example, the payload contains with the Video entity. The following payloads are returned for Video and App entity types:
Video
Video represents the identifying data for the piece of video content; for example, “Manchester by the Sea” might contain the following:
+
+
| Video Payload Fields | Description | Type | Example |
|---|---|---|---|
externalIds | Object | — | |
ASIN | The external ASIN of this entity | String | B01M3X9T06 |
└─ gracenote | The Gracenote identifier | String | MV0000000666661 |
userConfirmations | Object containing information about user confirmations for the item | Object | |
└─ entitlementVoiceActivation | Flag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - CONFIRMED (optional). | Enum; Default policy - unrecognized values are ignored | CONFIRMED |
uri | URI mapping to the video | URI | entity://provider/movie/manchesterbythesea |
value | The name of the video | String | Manchester by the Sea |
App
App represents the explicit app name specified by the user in utterance; for example, “Manchester by the Sea on Prime” might contain the following:
+
+
Examples of UI State Reports and UIController Directives
The following are examples showing sample screens, the UI state report sent, the customer’s utterance, and theDisplayDetails directive that Alexa sends to your Lambda.
Named Selection Example
In this example, the screen shows different titles on the screen. The customer wants to see details about a specific item that he or she names specifically. Screen the user sees:
UI state report you send
UI state report you send
Ordinal Selection Example
In this example, the screen shows content in different ordinals (positions such as number 1, 2, 3, etc.). The user wants to see details about a specific item and identifies the item with an ordinal rather than by naming the title. Screen the user sees:
UI state report you send
UI state report you send
"Select this” Example
In this example, the user selected a title (“The Marvelous Mrs. Maisel”) to view the details. The app presents the user with the content details. The user then says “select this.” This speech pattern is referred to as “anaphora” because the user changes the referent from a title (“The Marvelous Mrs. Maisel”) to a shorter abbreviation (“this”); in both cases, the referent refers to the same item. Screen the user sees:
UI state report you send
UI state report you send
Error Scenario When Asking for Detail About AMAZON.Thing Items
In the UI state report you send, you classify the elements on your screen with different entity types. These are described in Enum<EntityTypes> in theUIController documentation. If a customer asks for more detail about an element classified as a AMAZON.Thing, no MediaDetailsNavigator directives will be sent because an AMAZON.Thing isn’t a type of supported item for MediaDetailsNavigator.
Screen the user sees:
UI state report you send
UI state report you send
Sample App Integration
You can find a sample integration ofMediaDetailsNavigator in the cloudside sample app. The sample app includes Lambda code that shows how to declare support with the Discover directive for MediaDetailsNavigator and how to handle the DisplayDetails directives that MediaDetailsNavigator sends.
The following section contains a detailed use cases for the DisplayDetails directive from the sample app. You do not need to implement any of the classes or methods to test the sample app. The following code snippets show you where to implement, and how to use, required methods. You need to use your own logic in your application code.
To test with the sample app, change the UI content of any screen and test voice targeting the new UI contents with Alexa.
Display Details Directive
The sample app receives the directives from Alexa through Lambda. The directive is calledDisplayDetails, in the onMessage method.

