Developer Console
Merci de votre visite. Cette page est disponible en anglais uniquement.

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:

GetDisplayableItemsMetadata Directive and Lambda GetDisplayableItemsMetadataResponse

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.

Payload Descriptions
Field Description Data Type



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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                                "size": "X_SMALL",
                                "widthPixels": 480,
                                "heightPixels": 320
                            },
                            {
                                "url": "http://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": "http://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": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://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": "http://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": "http://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": "http://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        },
                        {
                            "url": "http://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.

Payload Descriptions
Field Description Data Type












































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"
            }
        }
    ]
}