Developer Console
Sign In
Sign In
Developer Console

GetPlayableItemsMetadata Directives (VSK Echo Show)

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.

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifier": {
                    "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
                }
        }
    }
}

The directive for a channel change GetPlayableItemsMetadata is identical except that the mediaIdentifier might have a different id, such as this:

"payload": {
    "locale": "en-US",
    "mediaIdentifier": {
            "id": "channelId://provider1.dvr.rp.1234-2345-63434-asdf"
        }
}

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

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.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": true
}

"advertising": {
    "advertisingId": "00000000-0000-0000-0000-00000000",
    "limitAdTracking": true
}

The following example shows settings that indicate that the customer chose to receive interest-based ads.

"advertising": {
    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
    "limitAdTracking": false
}

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.

{

    "directive": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "0f918d6e-ebae-48f1-a237-13c6f5b9f5da",
            "name": "GetPlayableItemsMetadata",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "videoDevice-001",
            "cookie": {
            }
        },
        "payload": {
            "locale": "en-US",
            "mediaIdentifier": {
                "id": "recordingId://provider1.dvr.rp.1234-2345-63434-asdf"
            },
            "requestContext": {
                "advertising": {
                    "advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
                    "limitAdTracking": false
                }
            }
        }
    }
}

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 code example above, 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:

"playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",

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.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "The Big Bang Theory",
                    "contentType": "ON_DEMAND",
                    "series": {
                        "seasonNumber": "1",
                        "episodeNumber": "2",
                        "seriesName": "The Big Bang Theory",
                        "episodeName": "The Terminator Decoupling"
                    },
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "absoluteViewingPositionMilliseconds": 1232340
                }
            ]
        }
    }
}

Example Response for a LIVE movie

The following response shows an example response for live content.

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true",
                                     "start": "2018-01-24T00:00:00Z",
                                     "end": "2018-01-24T02:30:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Example Response for Channel Change Scenario

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

{
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "38ce5b22-eeff-40b8-a84f-979446f9b27e",
            "name": "GetPlayableItemsMetadataResponse",
            "namespace": "Alexa.VideoContentProvider",
            "payloadVersion": "3"
        },
        "payload": {
            "searchResults": [
                {
                    "name": "Interstellar",
                    "contentType": "LIVE",
                    "playbackContextToken": "{\"streamUrl\": \"http:\/\/samplemediasite.com\/sample\/video.mp4\", \"title\": \"Some Video Title\"}",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "Alternate Channel Name"
                            },
                           "airingDetails": [
                                 {
                                     "isLiveBroadcast": "true",
                                     "start": "2018-01-24T00:00:00Z",
                                     "end": "2018-01-24T02:30:00Z"
                                 }
                             ]
                        }
                    ]
                }
            ]
        }
    }
}

Payload Descriptions

The following table describes the payload for a GetPlayableItemsMetadataResponse response.

Payload Descriptions
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: Interstellar

 String

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_DEMAND

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

String
affiliateCallSign(channel)
optional		 Specifies a channel by local affiliate call sign such as KCTS9.

Example: KCTS9

 String
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, false

 boolean
start
optional

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.
end
optional

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

 Long

Last updated: Mar 28, 2023