Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Develop
Test
Publish
Monetize
Engage users
Device specifications
Resources
Skip to main content
When users make requests to see more detail about a particular item (for example, “show more details about <video title>”), the 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

The Alexa.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 a DisplayDetails 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]
“[entity in focus]” means the customer has an element selected on the screen. The following table shows this utterance translated appropriately in different locales.

Sending UI State Reports

Follow same process as outlined in UIController for sending the UI state report.

VSK-Enabled Apps

You need to add support for MediaDetailsNavigator 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 for MediaDetailsNavigator as follows:
To indicate support for 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.
EntityDescription
VideoVideo represents the identifying data for the piece of video content.
AppApp 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 the UIController 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, the MediaDetailsNavigator interface sends a directive with the name DisplayDetails to your Lambda. The following is an example directive:

Payload Definitions

The payload 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 FieldsDescriptionTypeExample
externalIdsObject—
ASINThe external ASIN of this entityStringB01M3X9T06
└─ gracenoteThe Gracenote identifierStringMV0000000666661
userConfirmationsObject containing information about user confirmations for the itemObject
└─ entitlementVoiceActivationFlag to inform partner if voice enablement of viewing period or entitlement is successful. Possible values - CONFIRMED (optional).Enum; Default policy - unrecognized values are ignoredCONFIRMED
uriURI mapping to the videoURIentity://provider/movie/manchesterbythesea
valueThe name of the videoStringManchester 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 the DisplayDetails 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: Example 1
Customer utterance: “Alexa, show details on Captain fantastic”

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: Example 1 - ordinal
Customer utterance: “Alexa, show details on number one"

"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: Example 2
Customer utterance: “Alexa, select this”

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 the UIController 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: Example 5
Customer utterance: “Alexa, select captain fantastic”
No directive sent as the focussed UI element is of type AMAZON.Thing and “show details” is not supported for these entity types. A suitable message indicating this should be sent to the customer.

Sample App Integration

You can find a sample integration of MediaDetailsNavigator 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 called DisplayDetails, in the onMessage method.
For more details on the sample app configuration, see Alexa.UIController Interface (VSK Fire TV).
Last modified on October 13, 2021