Developer Console

Alexa.MediaDetailsNavigator (VSK Fire TV)

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.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

Show details on interstellar

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

montre les informations sur [VideoName]

*affiche moi plus de détails à propos de [VideoName]

voir plus d'infos sur [VideoName]

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

montre les informations sur [VideoName]

*affiche moi plus de détails à propos de [VideoName]

voir plus d'infos sur [VideoName]

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

zeig mir mehr details über [VideoName] an

details zu [VideoName] sehen

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

interstellar की जानकारी दिखाओ

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

*mostra mi ulteriori informazioni/dettagli su aladdin

*mostra mi / vedi dettagli su aladdin

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

坂道のアポロンの詳細を見せて

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

Procurar/procura/procure por todos Mostrar/mostra/mostre

detalhes Mostrar/mostra/mostredetalhes do [VideoName]

More details about a title are shown.

Feature Sample Utterances Expected Response
Show/see details on [title]
Optional

muéstra me información de aladín

enséña me información de aladín

ver detalles sobre enséña aladín

ver detalles de aladín

More details about a title are shown.

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.

    private void initializeAlexaClient() {
        // Retrieve the shared instance of the AlexaClientManager
        final AlexaClientManager clientManager = AlexaClientManager.getSharedInstance();

        // Gather your Skill ID
        final String alexaSkillId = "<insert skill id>";

        // Create a list of supported capabilities in your skill.
        final List<AlexaVideoCapability> supportedCapabilities = new ArrayList<>();
        supportedCapabilities.add(getAlexaChannelControllerCapability());
        supportedCapabilities.add(getAlexaPlaybackControllerCapability());
        supportedCapabilities.add(getAlexaRemoteVideoPlayerCapability());
        supportedCapabilities.add(getAlexaSeekControllerCapability());
        supportedCapabilities.add(getAlexaKeypadControllerCapability());
        supportedCapabilities.add(getAlexaUIControllerCapability()); //add support for the UI Controller
        supportedCapabilities.add(getMediaDetailsNavigatorCapability()); //add support for MediaDetailsNavigator

        // Initialize the client library by calling initialize().
        clientManager.initializeClient(getApplicationContext(),
                alexaSkillId,
                AlexaClientManager.SKILL_STAGE_DEVELOPMENT,
                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:

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "93e434b3-74ee-4a87-aad8-317a363ceb6d",
            "name": "Discover.Response",
            "namespace": "Alexa.Discovery",
            "payloadVersion": "3.0"
        },
        "payload": {
            "endpoints": [
                {
                    "capabilities": [
                        {
                            "interface": "Alexa.MediaDetailsNavigator",
                            "type": "AlexaInterface",
                            "version": "3.0",
                            "configurations": {
                                "entityTypes": [
                                    "Video",
                                    "App"
                                ]
                            }
                        }
                    ],
                    "cookie": {
                        "cookie1": "key1",
                        "cookie2": "key2"
                    },
                    "description": "Device description that's shown to the customer",
                    "endpointId": "Unique Device Identifier",
                    "friendlyName": "Upstairs Amazon Player",
                    "manufacturerName": "Amazon"
                }
            ]
        }
    }
}

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.

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

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9451490f-9457-4197-93be-200f9e37b776",
            "name": "DisplayDetails",
            "namespace": "Alexa.MediaDetailsNavigator",
            "payloadVersion": "3.0"
        },
        "payload": {
            "entity":
                {
                    "externalIds": {
                        "mediaBrowseId": "ref1"
                    },
                    "value": "Captain Fantastic",
                    "type": "Video"
                }
         }
    }
}

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

App Payload Fields Description Type Example
externalIds Object
└─ ENTITY_ID An application identifier from a list of apps. String amzn1.alexa-ask-target.app.72095
value The name of the application String Prime Video

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
{
  "context": {
    "properties": [

    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "AMAZON.BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-001"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "AMAZON.PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.UIController",
            "name": "uiElements",
            "value": {
              "scene": {
                "sceneId": "scene-id-004"
              },
              "elements": [
                {
                  "entity": {
                    "type": "AMAZON.ItemList",
                    "externalIds": {
                      "entityId": "webpage-001"
                    }
                  },
                  "elementId": "elementId-001",
                  "uiSupportedActions": [
                    "SCROLL_DOWN",
                    "SCROLL_FORWARD"
                  ],
                  "elements": [
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Iron Man"
                        },
                        "externalIds": {
                          "entityId": "video-001"
                        }
                      },
                      "ordinal": 1,
                      "elementId": "elementId-002",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Interstellar"
                        },
                        "externalIds": {
                          "entityId": "video-002"
                        }
                      },
                      "ordinal": 2,
                      "elementId": "elementId-003",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Captain Fantastic"
                        },
                        "externalIds": {
                          "entityId": "video-003"
                        }
                      },
                      "ordinal": 3,
                      "elementId": "elementId-004",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "The Dressmaker"
                        },
                        "externalIds": {
                          "entityId": "video-004"
                        }
                      },
                      "ordinal": 4,
                      "elementId": "elementId-005",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Gaurdians of the Galaxy"
                        },
                        "externalIds": {
                          "entityId": "video-005"
                        }
                      },
                      "ordinal": 5,
                      "elementId": "elementId-006",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Passengers"
                        },
                        "externalIds": {
                          "entityId": "video-006"
                        }
                      },
                      "ordinal": 6,
                      "elementId": "elementId-007",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    }
                  ]
                }
              ]
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Customer utterance: "Alexa, show details on Captain fantastic"

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9451490f-9457-4197-93be-200f9e37b776",
            "name": "DisplayDetails",
            "namespace": "Alexa.MediaDetailsNavigator",
            "payloadVersion": "3.0"
        },
        "payload": {
            "entity":
                {
                    "externalIds": {
                        "mediaBrowseId": "ref1"
                    },
                    "value": "Captain Fantastic",
                    "type": "Video"
                }
         }
    }
}

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
{
  "context": {
    "properties": [

    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "AMAZON.BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-001"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "AMAZON.PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.UIController",
            "name": "uiElements",
            "value": {
              "scene": {
                "sceneId": "scene-id-004"
              },
              "elements": [
                {
                  "entity": {
                    "type": "AMAZON.ItemList",
                    "externalIds": {
                      "entityId": "webpage-001"
                    }
                  },
                  "elementId": "elementId-001",
                  "uiSupportedActions": [
                    "SCROLL_DOWN",
                    "SCROLL_FORWARD"
                  ],
                  "elements": [
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Iron Man"
                        },
                        "externalIds": {
                          "entityId": "video-001"
                        }
                      },
                      "ordinal": 1,
                      "elementId": "elementId-002",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Interstellar"
                        },
                        "externalIds": {
                          "entityId": "video-002"
                        }
                      },
                      "ordinal": 2,
                      "elementId": "elementId-003",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Captain Fantastic"
                        },
                        "externalIds": {
                          "entityId": "video-003"
                        }
                      },
                      "ordinal": 3,
                      "elementId": "elementId-004",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "The Dressmaker"
                        },
                        "externalIds": {
                          "entityId": "video-004"
                        }
                      },
                      "ordinal": 4,
                      "elementId": "elementId-005",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Gaurdians of the Galaxy"
                        },
                        "externalIds": {
                          "entityId": "video-005"
                        }
                      },
                      "ordinal": 5,
                      "elementId": "elementId-006",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.VideoObject",
                        "name": {
                          "value": "Passengers"
                        },
                        "externalIds": {
                          "entityId": "video-006"
                        }
                      },
                      "ordinal": 6,
                      "elementId": "elementId-007",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    }
                  ]
                }
              ]
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Customer utterance: "Alexa, show details on number one"

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9451490f-9457-4197-93be-200f9e37b776",
            "name": "DisplayDetails",
            "namespace": "Alexa.MediaDetailsNavigator",
            "payloadVersion": "3.0"
        },
        "payload": {
            "entities":
                {
                    "externalIds": {
                        "mediaBrowseId": "ref1"
                    },
                    "value": "Iron man",
                    "type": "Video"
                }
          }
    }
}

"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
{
  "context": {
    "properties": [

    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "AMAZON.BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "endpoint-001"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.UIController",
            "name": "uiElements",
            "value": {
              "scene": {
                "sceneId": "scene-id-001"
              },
              "elements": [
                {
                  "entity": {
                    "type": "AMAZON.VideoObject",
                    "name": {
                      "value": "The Marvelous Mrs. Maisel"
                    },
                    "externalIds": {
                      "entityId": "video-001"
                    }
                  },
                  "elementId": "element-010",
                  "uiSupportedActions": [
                    "SELECT"
                  ],
                  "elements": [
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Watch Now with Prime"
                        },
                        "externalIds": {
                          "entityId": "webPageButton-001"
                        }
                      },
                      "elementId": "element-011",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Seasons & Episodes"
                        },
                        "externalIds": {
                          "entityId": "webPageButton-002"
                        }
                      },
                      "elementId": "element-012",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Add to Watchlist"
                        },
                        "externalIds": {
                          "entityId": "webPageButton-003"
                        }
                      },
                      "elementId": "element-013",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "More Ways to Watch"
                        },
                        "externalIds": {
                          "entityId": "webPageButton-003"
                        }
                      },
                      "elementId": "element-013",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },                    
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "CUSTOMERS ALSO WATCHED"
                        },
                        "externalIds": {
                          "entityId": "webPageButton-004"
                        }
                      },
                      "elementId": "element-014",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                  ]
                }
              ]
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          },
          {
            "namespace": "Alexa.UIController",
            "name": "focusedUIElement",
            "value": {
              "scene": {
                "sceneId": "scene-id-001"
              },
              "element": {
                "entity": {
                  "type": "AMAZON.Thing",
                  "name": {
                    "value": "Watch Now with Prime"
                  },
                  "externalIds": {
                    "entityId": "webPageButton-003"
                  }
                },
                "elementId": "element-013",
                "uiSupportedActions": [
                  "SELECT"
                ]
              }
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

Customer utterance: "Alexa, select this"

{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "<the identifier of the target endpoint>",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "9451490f-9457-4197-93be-200f9e37b776",
            "name": "DisplayDetails",
            "namespace": "Alexa.MediaDetailsNavigator",
            "payloadVersion": "3"
        },
        "payload": {
            "entity":
                {
                    "externalIds": {
                        "entityId": "video-001"
                    },
                    "value": "The Marvelous Mrs. Maisel",
                    "type": "Video"
                }

        }
    }
}

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
{
  "context": {
    "properties": []
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "avl-endpoint-id-001"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.UIController",
            "name": "uiElements",
            "value": {
              "scene": {
                "sceneId": "scene-id-004"
              },
              "elements": [
                {
                  "entity": {
                    "type": "AMAZON.Thing"
                  },
                  "elementId": "uiNode-000",
                  "uiSupportedActions": [
                    "SCROLL_FORWARD",
                    "SCROLL_DOWN"
                  ],
                  "elements": [
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Home"
                        }
                      },
                      "elementId": "uiNode-001",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Shows"
                        }
                      },
                      "elementId": "uiNode-002",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "IMDB FREEDIVE MOVIES AND TV-FREE WITH ADS"
                        }
                      },
                      "elementId": "uiNode-010",
                      "uiSupportedActions": []
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Captain Fantastic"
                        }
                      },
                      "elementId": "uiNode-011",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Fringe"
                        }
                      },
                      "elementId": "uiNode-012",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Drive"
                        }
                      },
                      "elementId": "uiNode-013",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Forte"
                        }
                      },
                      "elementId": "uiNode-014",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                    {
                      "entity": {
                        "type": "AMAZON.Thing",
                        "name": {
                          "value": "Padington"
                        }
                      },
                      "elementId": "uiNode-015",
                      "uiSupportedActions": [
                        "SELECT"
                      ]
                    },
                  ]
                }
              ]
            },
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

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 section below 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 below to test the sample app. The code snippets below 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.

protected void onMessage(final Intent intent) {
    Log.d(TAG, MessageFormat.format("Recieved a message from ADM: {0}", intent.toString()));
    
    //...
    else if ("DisplayDetails".equals(directiveName)) {

                // Checks json object
                if (!jsonTree.isJsonObject()) {
                    // Invalid message JSON
                    Log.e(TAG, "Invalid message JSON");
                    return;
                }

                // Extracts the underlying directive and payload
                final JsonObject jsonObject = jsonTree.getAsJsonObject();

                final JsonObject jDirective = jsonObject.get("directive").getAsJsonObject();
                final JsonElement jPayload = jDirective.get("payload");

                // Checks payload
                if (jPayload == null || !jPayload.isJsonObject()) {
                    // Invalid payload
                    Log.e(TAG, "Invalid payload; payload is null or not a JsonObject");
                    return;
                }

                final String jPayloadString = jPayload.getAsJsonObject().toString();

                final MediaDetailsElement mediaDetailsElement = gson.fromJson(jPayloadString, MediaDetailsElement.class);
                Log.d(TAG, "The MediaDetailsNavigator directive is " + mediaDetailsElement);

                // Validates directive
                if (!isMediaDetailsElementValid(mediaDetailsElement)) {
                    Log.e(TAG, "The received MediaDetailsElement directive is invalid. Cannot process it.");
                    return;
                }

                final Intent mediaDetailsIntent = new Intent();
                final String currentSceneId = getCurrentSceneId();
                final String packageName = FireTVApp.getInstance().getPackageName();
                if (HOME_BROWSER_SCENE_IDENTIFIER.equals(currentSceneId)) {
                    Log.d(TAG, MessageFormat.format("Setting the destination of mediaDetailsElement intent to Home Screen: {0}",
                            MainActivity.class.getName()));
                    mediaDetailsIntent.setClassName(packageName, MainActivity.class.getName());
                } else if (VIDEO_DETAIL_SCENE_IDENTIFIER.equals(currentSceneId)) {
                    Log.d(TAG, MessageFormat.format("Setting the destination of mediaDetailsElement intent to Detail Screen: {0}",
                            DetailsActivity.class.getName()));
                    mediaDetailsIntent.setClassName(packageName, DetailsActivity.class.getName());
                } else {
                    Log.w(TAG, MessageFormat.format("Current screen does not have items to display details of. Current scene: {0}", currentSceneId));
                    return;
                }

                mediaDetailsIntent.setAction(ACTION_ON_MEDIA_DETAILS);
                mediaDetailsIntent.setFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_NEW_TASK);

                // Adds entries from entity to intent
                mediaDetailsIntent.putExtra(EXTRA_MEDIA_DETAILS_NAVIGATOR_TYPE, mediaDetailsElement.getEntity().getType());
                mediaDetailsIntent.putExtra(EXTRA_MEDIA_DETAILS_NAVIGATOR_VALUE, mediaDetailsElement.getEntity().getValue());
                final ExternalIds externalIds = mediaDetailsElement.getEntity().getExternalIds();
                if (externalIds != null) {
                    Log.d(TAG, MessageFormat.format("externalIds is present: {0}", externalIds));
                    mediaDetailsIntent.putExtra(EXTRA_MEDIA_DETAILS_NAVIGATOR_ENTITY_ID, externalIds.getEntityId());
                }

                Log.d(TAG, MessageFormat.format("Sending the mediaDetailsElement intent: {0}", mediaDetailsIntent));
                FireTVApp.getInstance().startActivity(mediaDetailsIntent);
                Log.d(TAG, "Finished processing the DisplayDetails directive");
            } else {
                Log.e(TAG, "Unknown directive received.");
            }
        }
    }

For more details on the sample app configuration, see Alexa.UIController Interface (VSK Fire TV).


Last updated: Oct 13, 2021