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
Immediately after Alexa receives your Lambda’s response to GetPlayableItems, the VideoContentProvider API sends a GetPlayableItemsMetadata directive as a follow-up to get metadata for the items returned in GetPlayableItems. The following diagram shows the Alexa directive and Lambda response. GetPlayableItemsMetadataItems Directive and Lambda GetPlayableItemsMetadataResponse

Utterances for GetPlayableItemsMetadata Directives

No utterances prompt Alexa to send GetPlayableItemsMetadata directives. Instead, Alexa sends this directive as a follow-up after receiving your Lambda’s response to GetPlayableItems.

Handling GetPlayableItemsMetadata Directives

The purpose of GetPlayableItemsMetadata is to retrieve metadata necessary to initiate playback of the requested item. Your Lambda response should include basic metadata so that Alexa can render the correct voice response and initiate playback of the content. Similar to GetDisplayableItemsMetadata, the GetPlayableItemsMetadata directive contains only the content id values for which Alexa needs metadata (to play the media). Your response should not include any metadata that would be needed to display search results.

GetPlayableItemsMetadata Example

The following is a sample GetPlayableItemsMetadata directive. In this example, Alexa requests metadata for a mediaIdentifier with a value of recordingId://provider1.dvr.rp.1234-2345-63434-asdf. Only return metadata for those entity id values specified in the GetPlayableItemsMetadata directive.
The directive for a channel change GetPlayableItemsMetadata is identical except that the mediaIdentifier might have a different id, such as this:
In this case, the id is related to a channel rather than a specific media title.

Advertising object

The advertising object provides the customer’s advertising ID and preference for receiving interest-based ads. Alexa includes the advertising object in requests to video skills that declare that they deliver advertising. For more details, see About Alexa Advertising ID. To receive Alexa advertising IDs, you must indicate that your skill delivers advertising, publish a privacy policy, and submit your skill for recertification.

Structure of the advertising object

PropertyDescriptionTypeRequired?
advertisingIdA customer-resettable, unique identifier that maps to the ifa attribute of the OpenRTB API specification.It’s formatted as a version 4 UUID string, separated by dashes (8-4-4-4-12).Example: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367.StringYes
limitAdTrackingIndicates whether the customer wants to receive interest-based ads. Set to true when the customer opts out of interest-based ads. The limitAdTracking property maps to the lmt attribute of the OpenRTB API specification.BooleanYes
Example settings
The following are examples of settings that indicate that the customer chose not to receive interest-based ads.
The following example shows settings that indicate that the customer chose to receive interest-based ads.

Video Skill API required for advertising

To allow for in-stream advertising during playback, the following Alexa Video Skill APIs will include the requestContext object in the GetPlayableItemsMetadata payload. This object will contain the advertising context which contains the customer’s advertising preferences. Update your skill’s code for applicable APIs to consume the advertising object. For details about these APIs, see Directives Alexa Sends. Design your skill to use the advertising object from each request. In your code, precede any access to the advertisingId with code to verify the limitAdTracking flag. If limitAdTracking == true, you must honor the customer’s choice and disable tracking. Don’t cache the advertising properties because the customer can reset their ID and change their preference to receive interest-based ads at any time during or after the skill session. Alexa sends the latest values in the next request to your skill. Don’t associate the new advertisingId with a previous advertisingId or data tied to a previous advertisingId unless the customer has provided explicit consent for you to do so. Also, don’t associate any personal data with the advertisingId unless the customer has provided explicit consent for you to do so. When the customer chooses not to receive interest-based ads, the advertisingId is available for analytics, but you must disable tracking and interest-based ads. In some requests, Alexa might not include the advertising object. Design your skill to run with and without the advertisingId. You must honor the customer’s opt-out choice.
Example GetPlayableItemsMetadata request
The following is an example of a GetPlayableItemsMetadata request with the advertising object.

Lambda Response

Your Lambda’s response, GetPlayableItemsMetadataResponse, should contain only metadata information required for playback and for rendering any success prompts before playing the video. Although the GetPlayableItemsMetadataResponse is highly similar to GetDisplayableItemsMetadataResponse, the GetPlayableItemsMetadataResponse contains the playbackContextToken. This token contains an identifier that Alexa will pass on to your web player. The playbackContextToken is an identifier you choose related to your media. Alexa sends the playbackContextToken to your web player, and your web player can convert the identifier into a playback URL. This process is explained in Step 4: Understand How Your Web Player Gets the Media Playback URL. In the previous code example, the playbackContextToken is a stringified object (a key-value pair consisting of streamUrl and title parameters) because this is the format the sample web player expects:
Depending on how you code your web player to process this identifier, you might simply use a string or some other format. The responses for ON_DEMAND (VOD) media differs from the responses for LIVE (linear) media. Not only does the contentType differ, LIVE responses contain networkDetails.

Example Response for an ON_DEMAND TV Show

The following response shows an example for video-on-demand (VOD) content.

Example Response for a LIVE movie

The following response shows an example response for live content.

Example Response for Channel Change Scenario

The following is an example response for a channel change scenario.

Payload Descriptions

The following table describes the payload for a GetPlayableItemsMetadataResponse response.
Payload Descriptions
FieldDescriptionData Type
searchResults
required
The list of search resultsList
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: InterstellarString
optional
contentType
required
ContentType specifies the content type for the video that was returned in the search results. If you send a recorded movie or TV show, the contentType is set to RECORDING. If the result contains information about a live TV show, then the contentType is set to LIVE. If the result contains an on-demand content, then the contentType is set to ON_DEMAND.ContentType is also used to render a prompt to the user. For example, if the contentType is LIVE, Alexa renders a prompt such as, “Here’s the Academy Awards now airing on CBS.” If the contentType is RECORDING, Alexa renders a prompt such as, “Here’s the Academy Awards.”Examples: RECORDING, LIVE, ON_DEMANDEnum
playbackContextToken
required
Token that allows mapping of entities back to your system for further identification. You can send any string identifier as long as you can map it back to identify an entity on your side. This token is opaque to Alexa and is sent to the device for playback purposes. It can be the same media identifier that was used to fetch the metadata information (if that is what is needed for playback), or it can be a different serialized string with additional information that is required for playback.Note: If you’re using the sample web player, the playbackContextToken must be a JSON object converted to a string. The object must contain streamUrl and title key-value pairs. See Step 4: Understand How Your Web Player Gets the Media Playback URL for details.Opaque string
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.
  • REQUIRED: This means that parental control applies to this item based on the user’s setting. When this is set, there is a lock icon displayed on the item to suggest that parental control applies to this item and the user is required to enter a PIN to view the video.
  • NOT_REQUIRED: This means that parental control does not apply to this item based on the user’s setting.
Examples: REQUIRED, NOT_REQUIRED
Enum
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 (contentType = LIVE) on a channel, this object contains its metadata.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: PBSString
affiliateCallSign(channel)
optional
Specifies a channel by local affiliate call sign such as KCTS9.Example: KCTS9String
channelMetadata
optional
Provides additional information about the specified channel.Object
name (channelMetadata)
optional
Another value that identifies the channel, such as “FOX”.String
airingDetails
optional
This object contains information on when content airs.List
isLiveBroadcast
optional
Whether this content is airing in real time. Set this true for live events like watching an NFL football game, or award shows like Oscars or Emmys, etc., that are happening in real time.Set this false for content that was filmed prior to the original airing time. For example, a new episode of Big Bang theory that airs every Thursday. This must also be set to false for content that was once streamed in real time, like a football game in the past, but is no longer happening in real time.Examples: true, falseboolean
start
optional
The start time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.
end
optional
The end time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00ZA string in ISO 8601 format.
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 (contentType = LIVE) on a channel, this object contains its metadata.List
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: 1String
episodeNumber (series)
optional
The episode number of the video.Example: 3String
episodeName (series)
optional
The episode name.Example: 4String
seriesName (series)
optional
The name of the series.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: 1248625Long
Last modified on March 28, 2023