The Pipes2 JSON schema

info

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.

tip

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>",
}
}
}
]
}
tip

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 50 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"
}
info

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

info

the section property is not supported on Roku

(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

info

The duration is not supported on Roku

(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

info

The video_ads is not supported on Roku

note

Applicaster supports bot 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"
},
}
}

Currently Supported Players: Applicaster Player, THEO Player.

entry.extensions.analyticsCustomProperties

info

The analyticsCustomProperties is not supported on Roku

(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.

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.

entry.extensions.play_next_feed_url

info

The play_next_feed_url is not supported on Roku

(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

info

The play_next_feed_url is not supported on Roku

(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

info

The hqme extension is not supported on roku

(optional, boolean, relevant only for video typed entry) Flag which indicates whether a video entry is available for downloads

entry.extensions.resumeTime

info

The resumeTime property is not supported on Roku

(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

info

The progress property is not supported on Roku

(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

info

The auto_resume_completion_threshold property is not supported on Roku

(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

info

The share_url property is not supported on Roku

(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

info

The share_message property is not supported on Roku

(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

info

The signer_api property is not supported on Roku

(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.