The Pipes2 JSON schema
Even if you are not building Pipes2 endpoints, it's good to know what output it renders for debugging your apps.
Following is the documentation of the application/vnd+applicaster.pipes2+json content-type.
All Pipes2 endpoints should return their response in this format.
If you want to know how to implement your own Pipes2 Endpoints please read the
Implementing Pipes2 Endpoints doc.
The Structure of a Feed
A JSON Feed is a list items that may change over time. Think of a list of episodes, a list of shows or a playlist. These are all lists, and each could be described by a feed.
A JSON Feed starts with some info at the top: it says where the feed comes from, and may note its title and so on.
After that there’s an array of objects (entry) that describe each object in the list.
Example of a feed
{
"id": "560e97d0-bbbf-496e-8b9b-ac363d311167",
"type": {
"value": "feed"
},
"title": "Featured Episodes",
"entry": [
{
"type": {
"value": "video"
},
"id": "296bed86-11dc-43c3-9aaf-bfb25600ad2a",
"title": "Big Brother E1 S1",
"summary": "Pilot episode",
"media_group": [
{
"type": "image",
"media_item": [
{
"src": "https://example.com/images/big-brother-thumb.png",
"key": "thumbnail-16x9",
},
{
"src": "https://example.com/images/big-brother-thumb.png",
"key": "hero-4x3",
}
]
},
],
"content": {
"type": "video/hls",
"src": "https://example.com/big-brother-s1-e1.m3u8",
},
"extensions": {
"<Custom Key 1>": "<Custom Value 1>",
}
}
}
]
}
Use our online feed validator to validate Your feed
Fields
id
(required, string) A unique id for the feed.
title
(optional, string) is plain text. The title of the feed, used as the component header in the app.
type
(required, object) Should always be set to
"type": {
"value": "feed"
}
This field is required to support older versions of our SDKs
next
(optional, string) If the list is longer than 20 items, it's recommended to split the response to several pages. the next field holds the absolute URL to the next page on the list.
entry
(required, array) Holds the list feed items. See below all the entry item required and optional fields.
entry.id
(required, string) A unique id the represents the item.
entry.title
(optional, string) The title of the item.
entry.summary
(optional, string) The description of the item.
entry.type
(required, string) describes what screen type to open on the app when the end user taps on the item. You can set the type name according to your needs, but its recommend to use the following names if they fit:
- video - To open a full screen video player
- link - To open a link inside a webview
- show - To open the show screen
entry.content
(optional, object) describes what link to open when the end user taps on the item in the app.
Should always be an object with a key named src.
If the entry represents a video the content object should be constructed as follows:
{
"src": "<Absolute URL OF the Stream>",
"type": "video/hls"
}
If the entry represents an audio stream the content object should be constructed as follows:
{
"src": "<Absolute URL OF the MP3 Stream>",
"type": "audio"
}
When your stream URL is protected or signed its recommended not to pass it ins the content object. Zapp will use instead the entry id to retrieve the stream URL inside the player. Applicaster supports several providers to handle secure streams. Please consult your customer success representative for more info.
entry.media_group
(optional, array) holds the list of the entry thumbnails.
We support multiple thumbnails per entry.
Use the image key to represent its meaning, ratio and if needed resolution of the image.
{
"media_group": [
{
"type": "image",
"media_item": [
{
"src": "https://example.com/images/big-brother-thumb.png",
"key": "thumbnail-16x9"
},
{
"src": "https://example.com/images/big-brother-thumb.png",
"key": "hero-4x3"
}
]
}
]
}
entry.link
(optional, object) holds a link to reference the entry. This is mandatory for entries of type link, and will be used for the native share feature if present. If the entry should open a URL use the entry.link.href to set the URL absolute path.
{
"link": {
"href": "https://..."
}
}
Additionally, a rel: self attribute could be added as a reference to entry (to be used by other plugins such as Video Preload Plugin), .
{
"link": {
"rel": "self",
"href": "https://..."
}
}
entry.extensions
We use a list of known extensions to extend the capabilities of your app. See below the list of known extensions. You can also add custom extensions to each entry and use them when you render the entry in the component.
entry.extensions.section
(optional, string) optional category for an entry. Can be used to display a category badge when using one of the power cell plugins.
entry.extensions.duration
(optional, number) The duration of the entry in seconds.
Quick Brick power cells will convert the seconds to hh:mm:ss format on the client side.
entry.extensions.video_ads
Roku uses RAF and automatically pulls the ad tags from Roku's systems.
Applicaster supports both VAST & VMAP ads configuration in the DSP.
To see ads on your player you'll need to install the Google Interactive Media Ads plugin.
If you are using a custom player plugin (Not Applicaster), please make sure it supports our DSP protocol.
Currently Supported Players: Applicaster Player, THEO Player.
VAST
An object that describes how to add video ads in the VAST format.
Multiple ads can be added in an array form in the entry.
Each object in the video_ads array consists of the following fields:
offset: Determines when the ad should appear. For Preroll / Postroll, the value should be a String (either Preroll or Postroll - Please use case insensitive handling in the implementation), and for Midrolls the value should be an Integer, indicating the start time of the ad from the beginning of the video (in seconds).
ad_url: A url string of the VAST tag.
The object should be constructed as follows:
"extensions": {
"video_ads": [
{
"offset": "preroll",
"ad_url":"https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator="
},
{
"offset": 30,
"ad_url":"https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dredirectlinear&correlator="
},
{
"offset": "postroll",
"ad_url":"https://pubads.g.doubleclick.net/gampad
/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dskippablelinear&correlator="
}
],
}
VMAP
For VMAP you will just need to setup the URL of VMAP
"extensions": {
"video_ads": "https://pubads.g.doubleclick.net/example/ads?sz=
640x480&iu=/123/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpostpod&cmsid=496&vid=short_onecue&correlator="
}
entry.extensions.drm
If you are using a DRM protected content you should add the drm extension.
Currently Applicaster supports the following DRM protocols: widevine & playready for Android and FailrPlay for iOS/tvOS.
In some cases and on supported video players, additional data could be added to the drm provide object using the extension object.
"drm": {
"widevine": {
"license_url": "your_license_url",
// Optional data
"extensions": {
"custom_data": "..",
"integration": "keyos"
},
},
"playready": {
"license_url": "your_license_url",
// Optional data
"extensions": {
"custom_data": "..",
"integration": "keyos"
},
},
"fairplay": {
"certificate_url": "your_certificate_url",
"license_server_url": "your_license_server_url",
"license_server_request_content_type": "application/json", // supported values: "application/json", "text/plain"
"license_server_request_object_key": "server_playback_context", // can be "server_playback_context", "spc" or other key defined by the license server
// Optional data
"extensions": {
"custom_data": "..",
"integration": "keyos"
},
}
}
entry.extensions.chapter_markers
Chapter markers are used for segmentation of long videos. Here's more info about the Skip button.
"chapter_markers": {
"chapters": [
{
"id": "chapter_1",
"title": "Intro",
"start_time": "00:00",
"end_time": "1:00",
"actions": [{
"type": "show_skip",
"options": { "title": "Skip Intro" },
}]
},
{
"id": "chapter_2",
"title": "Recap",
"start_time": "01:00",
"end_time": "01:45",
"actions": [{
"type": "show_skip",
"options": { "title": "Skip Recap" },
}]
},
{
"id":"chapter_3",
"title": "Credits",
"start_time": "45:00",
"end_time": "48:00",
"actions": [{
"type": "show_play_next",
"options": {},
}]
}
]
}
entry.extensions.analyticsCustomProperties
(optional, object) You can add an object of key value properties to each entry. Once configured, whenever the app sends an event that relates to this entry, it will add those custom properties to the event.
Examples of common custom properties you might want to add: seasonName, showName etc.
entry.extensions.requires_authentication
(optional, boolean) If you integrated an authentication provider in your app,
use the field to let the app know that this item requires authentication to open. In case this field is set to true, the app will show a login screen before opening the item.
entry.extensions.free
(optional, boolean) If you integrated an SVOD provider in your app,
use the field to let the app knows this item if free. In case this field is set to true, the storefront screen will not be presented.
entry.extensions.ds_product_ids
(optional, string) If you integrated an TVOD/SVOD provider in your app,
use the field to list the entitlements needed to unlock the item. The ds_product_ids must be aligned to the product id as defined by the payment provider. More than one entitlement can be provided, as a Comma-Separated list of values (e.g. "offer1,offer2,offer3").
In some cases you will want to include multiple providers as entitlements. In this case use the following pattern: "provider1:product1,provider2:product2,provider3:product3".
When multiple entitlements are provided, that means that any of them provide authorization to the item, not that all of them are required. If the field is not provided or is left blank, and the entry does not include the free extension, that means that if a user will have any entitlement the item will be available for viewing.
entry.extensions.play_next_feed_url
(optional, string, relevant only to video typed entry) The Absolute URL of a feed to pass the player so it can recommend the next item to watch when the video is over.
entry.extensions.overlay_timestamp
(optional, number, relevant only to video typed entry) Number of seconds from the end of the current video at which point the next overlay will be presented.
entry.extensions.hqme
The hqme extension is not relevant for TV devices
(optional, boolean, relevant only for video typed entry) Flag which indicates whether a video entry is available for downloads
entry.extensions.resumeTime
(optional, number, relevant only to video typed entry) Number of seconds from the beginning of the video from which playback should start when playing this item
entry.extensions.progress
(optional, number, relevant only to video typed entry) Number between 0 and 1 indicating the current progress of a video entry. Can be used for cells to display a progress indicator
entry.extensions.auto_resume_completion_threshold
(optional, number, relevant only to video typed entry) Number of seconds from the end of a video which should consider the video as viewed.
For example, if a given video as 2mn of credits at the end, you can set this property to 120 and the Continue Watching plugin will consider this item fully viewed passed this point.
entry.extensions.share_url
The share_url property is only supported on mobile devices
(optional, string) optional url to use with the native share methods when sharing this entry. Will be used over the link provided in entry.link.href if present
entry.extensions.share_message
The share_message property is only supported on mobile devices
(optional, string) optional share message to use with the native share methods when sharing this entry. Will override the share message defined in the Native Share plugin configuration if present on an entry. Like the share message configuration key in the Native Share plugin, this field supports handlebars syntax for using values from the entry itself if needed.
{
"title": "A super cool show",
...
"extensions": {
"share_message": "Click here to watch {{ title }} !" // => "Click here to watch A super cool show !"
}
}
entry.extensions.signer_api
(optional, string) optional URL Signer service which will be used by Video Player Preload Plugin prior playing a video. More about Signed URLs.
Context keys will be added to the request, but it is expected the url will include all relevant query params.
entry.extensions.preview_playback
(optional, string) This is an optional URL for the preview stream source. If provided, this URL can be used by the Auto Play feature
entry.extensions.autoplay_settings
(optional, object) This is an optional object that, if specified, should provide configuration data for the Auto Play feature.
{
...
"extensions": {
"autoplay_settings": {
"start_time": "00:10",
"end_time": "00:35"
}
}
}
extensions.trailer_feed_url
(optional, string) This is an optional URL for the trailer button on the TV that contains feed with trailer URL. If provided, this URL can be used by the TV Trailer button.
{
"title": "A super cool show",
...
"extensions": {
"trailer_feed_url": "https://assets-production.applicaster.com/zapp/assets/accounts/617fe94bd22a630012a76496/static_feeds/feed-bdb9e373-139a-4e65-be4c-f873a46a131d.json"
}
}
extensions.actions
(optional, array) This is an optional array of actions. Currently add_to_calendar action is supported. If provided, the data can be used by the Add to Calendar Plugin.
{
"title": "Live Match 1",
...
"extensions": {
"actions": [
{
"type": "add_to_calendar",
"options": {
"title": "Scheduled Live Match 1", // use this to override the calendar event title, if not provided the entry title will be used.
"startDate": 1716895500000, // unix time in milis
"endDate": 1716920700000 // unix time in milis
}
}
],
}
}
entry.extensions.start_time_utc
(optional, string) Date and time in UTC format that can be transformed in different formats.