Developer Console
Sign In
Sign In
Developer Console

Badging (VSK Echo Show)

It is often useful to have badges, or contextual images, on search result tiles or over video playback to provide useful information to the user. This section covers the types of badges available, as well as their intended purpose.

Badges You Can Implement

The following table shows the types of display badges you can implement.

Badge Type Description
Recording This badge is displayed when the user is actively recording the content. This badge takes precedence over all other badges.
Live This badge is displayed when the content is currently airing in real time (for example, shows such as the Oscars, Emmys, and sports games).
On Now This badge is displayed when the content is airing on a channel at a given time, and is not considered Live.

In addition to badges, you should also show the Network logo or the Network call sign, which indicates where this piece of content is airing. For example, suppose a user says, "Show me comedy TV shows on [provider]." In such cases, [provider] can show content from multiple networks, such as ABC, HBO, CBS, and others. 

When you return such results on a multimodal device, you should also show a network logo on the bottom of the box art to indicate the origin of the content. If the network logo is not available, you should show the network call sign, such as ABC, HBO, etc. 

Content Freshness

You should also indicate whether the content is "new" with the search results metadata. This information comes from content providers and is displayed to indicate that this content is airing for the first time.

For example, if you search for episodes of "The Big Bang Theory," and episodes 1-5 were aired already and now episode 6 is available to view, content providers should let you know so that you can display "NEW" along with other metadata for that episode. 

You can specify badging in your skill through the GetDisplayableItemsMetadataResponse and GetPlayableItemsMetadataResponse responses from your Lambda. 

Badging APIs

To support badging, you should use the following structures within the GetDisplayableItemsMetadataResponse response payload: 

  • recording: Used to indicate if content is currently being recorded.
  • contentFreshness: Used to indicate whether the content is new.
  • networkDetails: Used to specify channel metadata.
  • airingDetails: Used to specify start and end times as well as whether content is airing live.

GetDisplayableItemsMetadataResponse Example

The following is an example GetDisplayableItemsMetadataResponse from your Lambda that includes badging.

{
    "payload": {
        "searchResults": [
            {
                "name": "Interstellar",
                "contentType": "LIVE",
                "releaseYear": "2011",
                "selectionAction": "PLAY",
                "thumbnailImage": {
                    "contentDescription": "InterstellarImage",
                    "sources": [
                        {
                            "url": "https://ecx.images-amazon.com/images/I/81nSh3pZUDL.RI.jpg",
                            "size": "X_SMALL",
                            "widthPixels": 480,
                            "heightPixels": 320
                        }
                    ]
                },
                "runtime": {
                    "runTimeInMilliseconds": 120931123,
                    "displayString": "2h30min"
                },
                "closedCaption": {
                    "status": "AVAILABLE",
                    "displayString": "CC"
                },
                "absoluteViewingPositionMilliseconds": 0,
                "parentalControl": {
                    "pinControl": "REQUIRED"
                },
                "viewingDisplayString": "PlayNow",
                "rating": {
                    "category": "PG-13"
                },
                "recording": {
                    "status": "RECORDING"
                },
                "contentFreshness": {
                    "state": "NEW"
                },
                "networkDetails": [
                    {
                        "channel": {
                            "number": "1234",
                            "callSign": "PBS",
                            "affiliateCallSign": "KCTS9",
                            "uri": "someUrl"
                        },
                        "channelMetadata": {
                            "name": "AlternateChannelName",
                            "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"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Payload Description

Payload Descriptions
Field Description Data Type
recording
optional

Information related to recording. The current structure only has a single field for status. The reason for making this a structure and not a standalone field is because Alexa Skills Kit may want to add some more information to the recording structure in the future. Having it available as an object allows Alexa Skills Kit to group these items and make it extensible for the future requirements.

 Object
status (recording)
optional

Recording status for the content. The following enum values are allowed:

  • RECORDED: This means that the content was previously recorded.
  • RECORDING: This means that the content is being actively recorded at the time of the request.
  • SCHEDULED: This means that the content is scheduled to be recorded at a future time.



Examples: RECORDED, RECORDING, SCHEDULED

 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 NEW — this means that the content is new and airing for the first time on the provider.



Example: NEW

 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 (contentType = LIVE) on a channel, this object contains its metadata.

 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

GetPlayableItemsMetadataResponse Example

The same networkDetails structure used in GetDisplayableItemsMetadata is also used for GetPlayableItemsMetadata. Here's a sample GetPlayableItemsMetadataResponse response:

{
    "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": "amzn1.dv.gti.b4a9f7c6-5def-7e63-9aa7-df38a479333e",
                    "parentalControl": {
                        "pinControl": "REQUIRED"
                    },
                    "networkDetails": [
                        {
                            "channel": {
                                "callSign": "PBS",
                                "affiliateCallSign": "KCTS9"
                            },
                            "channelMetadata": {
                                "name": "AlternateChannelName"
                            },
                            "airingDetails": [
                                {
                                    "isLiveBroadcast": "true",
                                    "end": "2018-01-24T02: 30: 00Z",
                                    "start": "2018-01-24T00: 00: 00Z"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Last updated: May 24, 2021