GetDisplayableItemsMetadata Directives (VSK Echo Show)
Immediately after Alexa receives your Lambda's response to GetDisplayableItems
, the VideoContentProvider API sends a GetDisplayableItemsMetadata
directive back to your Lambda. The purpose of the GetDisplayableItemsMetadata
directive is to retrieve information to properly show search results (not to play any content).
The following diagram shows the expected Alexa directive and Lambda response:
- Utterances for GetDisplayableItemsMetadata Directives
- Handling GetDisplayableItemsMetadata Directives
- GetDisplayableItemsMetadata Example
- Payload Descriptions
- Lambda Response
- Response Example
- Example Response Payloads
- Payload Descriptions
- Retrieve Image Size Data from the
mediaIdentifier
Object
Utterances for GetDisplayableItemsMetadata Directives
No utterances prompt Alexa to send GetDisplayableItemsMetadata
directives. Instead, Alexa sends this directive as a follow-up after receiving your Lambda's response to GetDisplayableItems
.
Handling GetDisplayableItemsMetadata Directives
Alexa sends GetDisplayableItemsMetadata
immediately before Alexa displays search results on the device. As such, Alexa might send this directive during search, browse, or landing page scenarios.
The directive contains only a list of id
values that Alexa needs metadata for. The id
values are returned from you during the previous GetDisplayableItemsResponse
that your Lambda sent.
Your Lambda's GetDisplayableItemsResponse
response should contain metadata for Alexa’s voice response to the user, as well as metadata about icons, badging, selectionAction
, etc.
Artwork returned to the user should be applicable to the title. The artwork should make it easier for the user to identify the content you are recommending from his or her search.
GetDisplayableItemsMetadata Example
The following is an example GetDisplayableItemsMetadata
directive:
{
"directive": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
"name": "GetDisplayableItemsMetadata",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "videoDevice-001",
"cookie": {
}
},
"payload": {
"locale": "en-US",
"mediaIdentifiers": [
{
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
},
{
"id": "channelId://provider1.channel.rp.1234-2345-63435-asdf",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
}
]
}
}
}
Payload Descriptions
The following table describes the payload
fields in the GetDisplayableItemsMetadata
directive.
Field | Description | Data Type |
---|---|---|
locale required |
The locale for the user that should be used to get displayable information for the search results. A locale in the same format specified for languages in in the Network Working Group Best Current Practice 47 (BCP-47). If you receive an unrecognized locale, default to Examples: |
String |
mediaIdentifiers required |
Contains a list of |
Array |
id required |
An identifier for the video item that is used to fetch any display or playback related metadata information on subsequent calls to |
String |
Lambda Response
Your Lambda's response must contain the metadata information required to populate the templates on the device (provided by Amazon) and render the search results on the screen. The response contains only display-related information — no playback information is required in this case.
Response Example
The following an example of a GetDisplayableItemsMetadataResponse
that your Lambda should send. This response provides a list of id
values for the items to display on the device.
{
"event": {
"header": {
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
"messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
"name": "GetDisplayableItemsMetadataResponse",
"namespace": "Alexa.VideoContentProvider",
"payloadVersion": "3"
},
"payload": {
"searchResults": [
{
"name": "The Big Bang Theory",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Purchase Options",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
},
{
"name": "The Big Bang Theory",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory Image ",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "30 min"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Play Now",
"rating": {
"category": "TV-PG"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "Alternate Channel Name",
"image": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
},
"airingDetails": [
{
"isLiveBroadcast": "true",
"end": "2018-01-24T02:30:00Z",
"start": "2018-01-24T00:00:00Z"
}
]
}
]
}
]
}
}
}
Example Response Payloads
The payload
object for the GetDisplayableItemsMetadataResponse
will contain different fields depending on the media. The following sample responses show the payload
for different types of media.
Example Response Payload for an ON_DEMAND Movie
{
"payload": {
"searchResults": [
{
"name": "Interstellar",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "Interstellar Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Purchase Options",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
Example Payload for an ON_DEMAND TV Show
{
"payload": {
"searchResults": [
{
"name": "The Big Bang Theory",
"contentType": "ON_DEMAND",
"releaseYear": "2014",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 49m"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"series": {
"seasonNumber": "1",
"episodeNumber": "1",
"seriesName": "The Big Bang Theory",
"episodeName": "Pilot"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Purchase Options",
"reviews": [
{
"totalReviewCount": 41951,
"type": "FIVE_STAR",
"ratingDisplayString": "4.06"
}
],
"rating": {
"category": "PG-13"
}
}
]
}
}
Example Payload for LIVE Content
{
"payload": {
"searchResults": [
{
"name": "Interstellar",
"contentType": "LIVE",
"releaseYear": "2011",
"selectionAction": "PLAY",
"thumbnailImage": {
"contentDescription": "Interstellar Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
}
]
},
"runtime": {
"runTimeInMilliseconds": 120931123,
"displayString": "2h 30 min"
},
"closedCaption": {
"status": "AVAILABLE",
"displayString": "CC"
},
"absoluteViewingPositionMilliseconds": 0,
"parentalControl": {
"pinControl": "REQUIRED"
},
"viewingDisplayString": "Play Now",
"rating": {
"category": "PG-13"
},
"networkDetails": [
{
"channel": {
"number": "1234",
"callSign": "PBS",
"affiliateCallSign": "KCTS9",
"uri": "someUrl"
},
"channelMetadata": {
"name": "Alternate Channel Name",
"image": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg"
},
"airingDetails": [
{
"isLiveBroadcast": "true"
"end": "2018-01-24T02:30:00Z",
"start": "2018-01-24T00:00:00Z"
}
]
}
]
}
]
}
}
Example Payload for Content That Can Be Browsed
{
"payload": {
"searchResults": [
{
"name": "The Big Bang Theory",
"contentType": "RECORDING",
"selectionAction": "BROWSE",
"thumbnailImage": {
"contentDescription": "The Big Bang Theory Image",
"sources": [
{
"url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
"size": "X_SMALL",
"widthPixels": 480,
"heightPixels": 320
},
{
"url": "https://ecx.images-amazon.com/AJhF52zkD7ObETpyTTW.jpg",
"size": "SMALL",
"widthPixels": 720,
"heightPixels": 480
}
]
},
"viewingDisplayString": "View episodes"
}
]
}
}
Payload Descriptions
The following table describes the payload
fields for a GetDisplayableItemsMetadataResponse
.
Field | Description | Data Type |
---|---|---|
searchResults required |
The list of search results | List |
name required |
The name of the video. This is used to render a prompt to the user about the video that is going to be played. For example, "Here's Interstellar." Example: |
String |
contentType required |
Examples: |
Enum |
itemType required |
After receiving your response ( Example: |
Enum |
releaseYear optional |
Release year of video. This is used to display the release year when showing the item on the screen. 2018 |
String |
selectionAction required |
Guidance on how to browse the entity when the user selects this item. For example, you may choose to group similar items together when sending the search results. Movies or TV shows can be grouped by Genre, or by Actor, etc. In such cases, you can drill down on the item by selecting the group and may view more results. The following enum values are allowed:
Examples: |
Enum |
thumbnailImage required |
Image information that is used to display an image for the result item on the screen. URL prefix must be Example: { "contentDescription": "string", "sources": [ { "url": "string", "size": "string", "widthPixels": integer, "heightPixels": integer }, { "url": "string", "size": "string", "widthPixels": integer, "heightPixels": integer }, { ... } ] } |
Object |
runtime optional |
Details about the video runtime. | Object |
runTimeInMilliseconds optional |
Duration of the video in milliseconds.
Example: |
Long |
displayString (runtime)optional |
The formatted display string for the duration of the video. This is used to show the duration on the screen.
Example: |
String |
closedCaption optional |
Details about whether closed caption is available for the video and display information. | Object |
status (closedCaption)optional |
Whether closed caption is available for the video. This is an enum with the following values:
Examples: |
Enum |
displayString (closedCaption)optional |
The formatted display string to be shown on the screen for closed caption. Example: |
String |
series optional |
The metadata about the series if this item is part of a series. This information should be populated for TV shows only. If available, the information here is used to render prompts to the user for example, "Here's 'The Big Bang Theory' Season 1, episode 4. |
Object |
seasonNumber (series)optional |
The season number of the video. Example: |
String |
episodeNumber (series)optional |
The episode number of the video. Example: |
String |
episodeName (series)optional |
The episode name. Example: |
String |
absoluteViewingPositionMilliseconds required |
Progress offset of video in milliseconds based on the user's watch history. If the user has watched it previously, this represents some offset greater than 0. This is used to display a progress bar on the result item indicating how much has the user watched previously. Example: |
Long |
parentalControl required |
Parental Control information based on the user and the video. |
Object |
pinControl required |
This field indicates whether parental control is required for the user for this video based on the setting. This is an enum with 2 values.
Examples: |
Enum |
viewingDisplayString optional |
The display string is shown on the screen with the result item and gives the user an indication of whether he/she can play immediately or has to go through buying/renting/subscribing, etc. Based on the entitlement status, the string can be different. The String needs to be localized based on the locale sent in the request Example: |
String |
reviews optional |
Information about the reviews for the video. | List |
totalReviewCount optional |
Total count of reviews for the video.
Example: |
Long |
type (review)optional |
The type of review upon which information is based.
Example: |
Enum |
ratingDisplayString optional |
Rating of the video based for the type mentioned above and the reviews. This is used to display the rating under each item in the search results.
Example: |
String |
rating optional |
Rating related information for the video. | Object |
ratingCategory optional |
Rating category of the video, such as PG-13. This rating applies for the region that this video is resolved from. Also the rating value may differ based on the content. For example, for movies you can send an MPAA rating like "PG-13"; for TV shows, you can send a TV parental guidelines rating like "TV-PG."
Example: |
String |
recording optional |
Information related to recording. The current structure only has a single field for |
Object |
status (recording)optional |
Recording status for the content. The following enum values are allowed:
Examples: |
String |
contentFreshness optional |
Details about content freshness. |
Object |
state (contentFreshness)optional |
Whether this content is new for the provider that Alexa is fetching results from. The only enum value allowed is Example: |
String |
networkDetails optional |
Network details gives information about the network the program is airing from. For example, a new episode of "The Big Bang Theory" airing from CBS, or a live soccer game airing from ESPN. For on-demand content, this could be, for example, Prime Video displaying Game of thrones results from HBO. If the result item represents a live show ( |
List |
channel optional |
Information about the channel the video is currently airing on. |
Object |
callSign (channel)optional |
Specifies a channel by call sign such as PBS.
Example: |
String |
affiliateCallSign (channel)optional |
Specifies a channel by local affiliate call sign such as KCTS9.
Example: |
String |
uri (channel)optional |
The URI of the channel such as "entity://provider/channel/12307" | |
channelMetadata optional |
Provides additional information about the specified channel. |
Object |
name (channelMetadata)optional |
Another value that identifies the channel, such as "FOX". | String |
image (channelMetadata)optional |
Example: |
String |
airingDetails optional |
This object contains information on when content airs. |
List |
isLiveBroadcast optional |
Whether this content is airing in real time. Set this Set this Examples: |
boolean |
end optional |
The end time of the time window. Examples: |
A string in ISO 8601 format. |
start optional |
The start time of the time window. Examples: |
A string in ISO 8601 format. |
mediaIdentifier required |
Identifier for the |
Object |
Retrieve Image Size Data from the mediaIdentifier
Object
The GetDisplayableItemsMetadata
API returns relevant information about the items in your catalog. One of these metadata fields is a thumbnail image URL, which is used to load images onscreen as part of the search results, landing page, and category selection. Echo Show devices come in varying sizes and resolutions, so the image containers that these URLs populate are of varying sizes and resolutions too. If the image that GetDisplayableItemsMetadata
returns doesn't fit the device that requested it, then the image might get distorted on some displays.
To avoid that, use data from the displayContext
object which belongs to the mediaIdentifier
.
How to Use the displayContext
Object Data
The displayContext
object provides you with the following fields:
Field | Type | Required? |
---|---|---|
imageAspectRatio |
Ratio (String) Currently, "2:1" , "16:10" or "16:9" |
Yes |
imageHeight |
Dimension (String) For example, "480px" |
No |
imageSize |
Enum See Properties for imageSize |
Yes |
imageWidth |
Dimension (String) For example, "270px" |
No |
With the imageWidth
and imageHeight
fields in the request, you know exactly what image size to use. You can also use the two other fields that bucket the images: one to specify the desired imageAspectRatio
and one for the imageSize
. If you don't provide the exact ratio or size requested, then your skill automatically scales images, first by trying to match the imageAspectRatio
, and then the imageSize
.
If you use multiple images rather than one, the API matches on imageAspectRatio
first to avoid stretching or cropping you images.
Below are the image properties that the API returns for each device. As a developer, you have the choice of providing images based on the level of granularity you decide. A 16:9 image, for example, displays at scale on all devices except the Echo Show 5, but if you prefer to offer an image of the exact resolution for each device, that option is also available to you.
Properties for imageSize
This table lists all the enum properties for the imageSize
field:
Property | Description | Recommended Size (in pixels) Width x Height |
---|---|---|
X_SMALL |
Displayed within extra small containers | 480 x 320 |
SMALL |
Displayed within small containers | 720 x 480 |
MEDIUM |
Displayed within medium containers | 960 x 640 |
LARGE |
Displayed within large containers | 1200 x 800 |
X_LARGE |
Displayed within extra large containers | 1920 x 1280 |
Supported Image Sizes for Echo Show Devices
Here are the supported image sizes:
Device | Device Resolution | Hero Title Resolution (px) |
Hero Title Aspect Ratio |
Search Result Resolution (px) |
Search Result Aspect Ratio |
---|---|---|---|---|---|
Echo Show 10 2nd Gen |
1280x800 | 1280x800 | 16:10 | 364x204 | 16:9 |
Echo Show 5 | 960x480 | 960x480 | 2:1 | 368x184 | 2:1 |
Echo Show 1st Gen |
1024x600 | 1024x600 | 16:10 | 564x320 | 16:9 |
Echo Show 8 | 1280x800 | 1280x800 | 16:10 | 522x293 | 16:9 |
Example Request
{
"locale": "en-US",
"mediaIdentifiers": [
{
"id": "recordingId://provider1.dvr.rp.1234-2345-63434-abcde",
"displayContext": {
"imageWidth": "480px",
"imageHeight": "270px",
"imageAspectRatio": "16:9",
"imageSize": "MEDIUM"
}
}
]
}
Last updated: May 24, 2021