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.
Utterances for GetPlayableItemsMetadata Directives
No utterances prompt Alexa to sendGetPlayableItemsMetadata directives. Instead, Alexa sends this directive as a follow-up after receiving your Lambda’s response to GetPlayableItems.
Handling GetPlayableItemsMetadata Directives
The purpose ofGetPlayableItemsMetadata 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 sampleGetPlayableItemsMetadata 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.
GetPlayableItemsMetadata is identical except that the mediaIdentifier might have a different id, such as this:
id is related to a channel rather than a specific media title.
Advertising object
Theadvertising 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
| Property | Description | Type | Required? |
|---|---|---|---|
advertisingId | A 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. | String | Yes |
limitAdTracking | Indicates 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. | Boolean | Yes |
Example settings
The following are examples of settings that indicate that the customer chose not 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 therequestContext 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 aGetPlayableItemsMetadata 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:
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 aGetPlayableItemsMetadataResponse response.
| Field | Description | Data Type |
|---|---|---|
searchResultsrequired | The list of search results | List |
namerequired | 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: Interstellar | String |
| optional | ||
contentTyperequired | 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_DEMAND | Enum |
playbackContextTokenrequired | 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 |
parentalControlrequired | Parental Control information based on the user and the video. | Object |
pinControlrequired | 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, NOT_REQUIRED | Enum |
networkDetailsoptional | 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 |
channeloptional | Information about the channel the video is currently airing on. | Object |
callSign (channel)optional | Specifies a channel by call sign such as PBS.Example: PBS | String |
affiliateCallSign(channel)optional | Specifies a channel by local affiliate call sign such as KCTS9.Example: KCTS9 | String |
channelMetadataoptional | Provides additional information about the specified channel. | Object |
name (channelMetadata)optional | Another value that identifies the channel, such as “FOX”. | String |
airingDetailsoptional | This object contains information on when content airs. | List |
isLiveBroadcastoptional | 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, false | boolean |
startoptional | The start time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z | A string in ISO 8601 format. |
endoptional | The end time of the time window.Examples: 2016-09-07T23:59:00+00:00, 2018-01-24T02:30:00Z | A string in ISO 8601 format. |
networkDetailsoptional | 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 |
seriesoptional | 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: 1 | String |
episodeNumber (series)optional | The episode number of the video.Example: 3 | String |
episodeName (series)optional | The episode name.Example: 4 | String |
seriesName (series)optional | The name of the series. | String |
absoluteViewingPositionMillisecondsrequired | 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: 1248625 | Long |

