Preplay API (Version 2)

Use the Preplay endpoint to:

Live Streaming (Live Channel): Retrieve a live channel's playback URL and information required to request the Ping endpoint.
Video On-Demand Streaming: Return ad break information before the start of playback.

Live Streaming (Live Channel)

This endpoint returns the following type of information:

A live channel's playback URL.
Information (i.e., session ID and the zone prefix) required when submitting requests to the Ping endpoint.
The start time and duration of each ad that took place during a given time period.

Retrieve additional ad information via the Ping endpoint.

Request

A Preplay request must include all of the parameters defined within the playback request. It must also include a digital signature if the Require a token for playback option is enabled on the corresponding live channel.

Request syntax:

https://content.uplynk.com/preplay/channel/<ChannelID>.json

https://content.uplynk.com/preplay/channel/ext/<UserID>/<ChannelExternalID>.json

Pass the following query string parameters:

Parameter	Description
ts	This request parameter must be defined in order to include ad data in the response. Defines the starting point, in Unix time, for which ad data will be reported.
endts	Defines the ending point, in Unix time, for which ad data will be reported. If this parameter is omitted, then ad data will be reported from the time defined by the ts parameter till the point in time at which the request was submitted. This parameter is only relevant when the request includes the ts parameter.
ad.sssb	Determines whether server-side beaconing will be suppressed. Typically, server-side beaconing is suppressed in order to allow the client to send beacon calls to one or more of the following: Ad platform Data management platform (e.g., comScore and eXelate) If server-side beaconing has been disabled, then video ad metrics (e.g., impressions, first quartile, midpoint, third quartile, etc.) will only be sent to the ad and/or data management platform when a client sends a beacon call. Server-side beaconing will not be triggered for VPAID (Video Player-Ad Interface Definition) ad units and therefore it is unnecessary to manually disable beaconing through this parameter. However, this also means that the player is responsible for displaying the ad, firing ad-related events, and beaconing. Suppress server-side beaconing by setting this parameter to 1 (i.e., ad.sssb=1). Server-side beaconing will be enabled when this parameter is missing or set to a different value.
ad.pingf	Requires Ping (v=3) API Enables the Linear Ad Data feature. You must enable the Linear Ad Data feature if you plan on requesting the Ping API with the v=3 query string parameter. Syntax: ad.pingf=4 Learn more about features.
rmt	Required for Studio DRM Identifies the type of DRM solution (i.e., Apple FairPlay Streaming (FPS), Google Widevine, or Microsoft PlayReady) through which playback will be protected. Valid values are: fps \| wv \| pr
manifest	Identifies the manifest type and determines whether FPS, Widevine, or PlayReady license URLs will be generated. Valid values are: m3u8: Default value. Populates the drm object with a fairplayCertificateURL key-value pair. mpd: Populates the drm object with playreadyLicenseURL and widevineLicenseURL key-value pairs.
thumbsray	Set this parameter to 1 to include trick play thumbnailsA player may use these thumbnails to provide visual feedback when a viewer fast forwards or rewinds the stream. in the manifest file for all subsequent requests within this playback session. Example: thumbsray=1

Response

The response for a successful request contains the following parameters:

Parameter	Data Type	Description
playURL	String	Indicates the playback URL sent to the player. Key information: This playback URL should not be modified under most circumstances. Exception If you are using the allowts playback URL parameter to allow scrubbingRefers to the process of jumping to a specific point in a video. This is typically performed through the player's timeline to either jump forwards or backwards through a video. through a DASH video, then your player must remove the pbs query string parameter from the playback URL returned by this property. Otherwise, the player will be unable to play the requested video. Do not depend on the format of this URL. We reserve the right to change the format of this URL as needed.
prefix	String	Indicates the zone prefix for the viewer's session. Use this prefix when submitting playback or API requests (e.g., Ping endpoint) for this session. Sample value: https://content-ause3.uplynk.com
sid	String	Indicates the playback session ID.
ads	Array	Contains a list of ads that took place during the time period defined by the ts and endts request parameters.
duration	Float	Indicates the duration, in seconds, of an ad break.
ts	Float	Indicates the start time, in Unix time, of an ad break.
extensions	Array	VAST Only Contains the custom set of VAST extensions returned by the ad server. Each custom extension is reported as an object. Learn more.
fw_parameters	Object	FreeWheel Only If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object. Learn more.
drm	Object	Studio DRM Only The response may include this object when Studio DRM has been activated on your account. Learn more (FairPlay Streaming Only). This object contains a fairplayCertificateURL key-value pair when both of the following conditions are true: The Preplay API was requested with rmt=fps. You have uploaded key information from your FPS deployment package. required Boolean Indicates whether Studio DRM is required for playback. fairplayCertificateURL String Indicates the URL to a hosted instance of your public FPS certificate. Learn more (DASH - Google Widevine DRM and PlayReady) Only. This object contains the widevineLicenseURL and playreadyLicenseURL key-value pairs provided that the Preplay API was requested with both of the following parameters: rmt: Either rmt=wv or rmt=pr manifest: manifest=mpd required Boolean Indicates whether Studio DRM is required for playback. widevineLicenseURL String Indicates the URL to a hosted instance of your public Google Widevine license. playreadyLicenseURL String Indicates the URL to a hosted instance of your public Microsoft PlayReady license. All of the URLs included in the drm object may be referenced from other domains without causing a cross-origin resource sharing (CORS) issue.

Sample Response

{
	'ads': [{
			'duration': 60.293708333333335,
			'ts': 1457033271.8485
		}, {
			'duration': 60.4043125,
			'ts': 1457034417.0621874
		}, {
			'duration': 60.0268125,
			'ts': 1457037981.8656042
		}
	],
	'playURL': 'https://content-ause3.uplynk.com/preplay2/channel/7ac2f0d27d4b929643652de654e2b8/f528764d644d212b3c21fbca0cb8d6/6K9u6kRTD54aInrt32DnNMVtJs2br2rrHTOY2.m3u8?pbs=bcb82775835b98b36d0a1a73100eaa',
	'prefix': 'https://content-ause3.uplynk.com',
	'sid': 'bcb82775835b98b36d0a1a73100eaa',
	'drm': {
			'required': false,
			'fairplayCertificateURL': 'https://x-drm.uplynk.com/fairplay/public_key/662d0a3da2244ca5b6757a7dd077e538.cer'
	}
}

On-Demand Streaming

This endpoint returns ad break information before the start of playback.

Request

Request syntax:

https://content.uplynk.com/preplay/<AssetID>.json

https://content.uplynk.com/preplay/ext/<UserID>/<ExternalID>.json

A Preplay request must include all parameters defined within the playback request. This request must also include a digital signature if the Require a token for playback option is enabled on the corresponding CMS asset.

Include the following query string parameters:

Parameter	Description
v Required	Determines which version of this endpoint will be requested. Set this parameter to "2."
jsonp	Defines the name of the JavaScript function call that will wrap the response. The file extension for this value must be ".js."
ad.sssb	Determines whether server-side beaconing will be suppressed. Typically, server-side beaconing is suppressed in order to allow the client to send beacon calls to one or more of the following: Ad platform Data management platform (e.g., comScore and eXelate) If server-side beaconing has been disabled, then video ad metrics (e.g., impressions, first quartile, midpoint, third quartile, etc.) will only be sent to the ad and/or data management platform when a client sends a beacon call. Server-side beaconing will not be triggered for VPAID (Video Player-Ad Interface Definition) ad units and therefore it is unnecessary to manually disable beaconing through this parameter. However, this also means that the player is responsible for displaying the ad, firing ad-related events, and beaconing. Suppress server-side beaconing by setting this parameter to 1 (i.e., ad.sssb=1). Server-side beaconing will be enabled when this parameter is missing or set to a different value.
ad.pingf	Requires Ping (v=3) API Enables one or more features. You must enable 1 or more features if you plan on requesting the Ping API with the v=3 query string parameter. Syntax: ad.pingf=Value Example: Pass the following parameter to enable both the Ad Impressions and Video Views features: ad.pingf=3 Learn more about features.
rmt	Required for Studio DRM Identifies the type of DRM solution (i.e., Apple FairPlay Streaming (FPS), Google Widevine, or Microsoft PlayReady) through which playback will be protected. Valid values are: fps \| wv \| pr
manifest	Identifies the manifest type and determines whether FPS, Widevine, or PlayReady license URLs will be generated. Valid values are: m3u8: Default value. Populates the drm object with a fairplayCertificateURL key-value pair. mpd: Populates the drm object with playreadyLicenseURL and widevineLicenseURL key-value pairs.

Response

The response for a successful request contains the following parameters:

Parameter	Data Type	Description
ads	Object	Contains ad information, such as break offsets and non-video ads. Learn more. Ad break information is returned for an asset that contains ad breaks regardless of whether the response from the ad decision server contains ads.
drm	Object	Studio DRM Only The response may include this object when Studio DRM has been activated on your account. Learn more (FairPlay Streaming Only). This object contains a fairplayCertificateURL key-value pair when both of the following conditions are true: The Preplay API was requested with rmt=fps. You have uploaded key information from your FPS deployment package. fairplayCertificateURL String Indicates the URL to a hosted instance of your public FPS certificate. Learn more (DASH - Google Widevine DRM and PlayReady) Only. This object contains the widevineLicenseURL and playreadyLicenseURL key-value pairs provided that the Preplay API was requested with both of the following parameters: rmt: Either rmt=wv or rmt=pr manifest: manifest=mpd widevineLicenseURL String Indicates the URL to a hosted instance of your public Google Widevine license. playreadyLicenseURL String Indicates the URL to a hosted instance of your public Microsoft PlayReady license. All of the URLs included in the drm object may be referenced from other domains without causing a cross-origin resource sharing (CORS) issue.
interstitialURL	String	Indicates the URL to the XML file containing interstitial information for Apple TV. This parameter reports null when ads are not found.
playURL	String	Indicates the playback URL sent to the player. This playback URL should not be modified under most circumstances. Do not depend on the format of this URL. We reserve the right to change the format of this URL as needed.
prefix	String	Indicates the zone prefix (e.g., https://content-ause2.uplynk.com/) for the viewer's session. Use this prefix when submitting playback or API requests (e.g., Ping endpoint) for this session.
sid	String	Indicates the playback session ID.

Ads Object

An ads object contains the following members:

Member	Data Type	Description
breaks	Array	A list of objects for every ad break in the ad response. This includes both linear and non-linear ads. For more information on the difference between linear and non-linear ads, see the VAST 3 specification document. This property loosely follows the structure and naming conventions of VMAP 1.0 with VAST 3.0 objects.
breakOffsets	Array	A list of objects that contain the ad break's timeOffset and the index for the ads.breaks object. This list only references breaks that contain video ads.
placeholderOffsets	Array	A list of objects with start and end times for every non-video ad that has been replaced with a short blank video (i.e., placeholder ad). Learn more about placeholder ads.

Member

Data Type

Description

breaks

Array

A list of objects for every ad break in the ad response. This includes both linear and non-linear ads. For more information on the difference between linear and non-linear ads, see the VAST 3 specification document.

This property loosely follows the structure and naming conventions of VMAP 1.0 with VAST 3.0 objects.

breakOffsets

Array

A list of objects that contain the ad break's timeOffset and the index for the ads.breaks object.

This list only references breaks that contain video ads.

placeholderOffsets

Array

A list of objects with start and end times for every non-video ad that has been replaced with a short blank video (i.e., placeholder ad).

Learn more about placeholder ads.

Ad Break (breaks) Object

Each ad break (breaks) object has an array of ads and information about the break type and position.

Member	Type	Description
events	Object	Contains events for the ad break.
ads	Array	A list of ad objects associated with this ad break.
type	String	Indicates the ad break type. Valid values are: linear \| nonlinear Learn more (VAST 3 specification document).
position	String	Indicates the position of the ad break. Valid values are: preroll \| midroll \| postroll \| pause \| overlay
timeOffset	Float	Indicates the start time of the ad break in the player timeline.
duration	Float	Indicates the duration of the ad break. VPAID: If the ad break includes a VPAID ad, this parameter will report the duration of the VPAID ad instead of the duration of the placeholder ad.

Ad Object

Each ad object in the preplayResp.ads.breaks.ads array describes an ad. This ad data includes the creative to display the ad, events, and companions corresponding to the ad. The properties for this object complies with the VAST 3 specification document.

For each non-video ad (e.g,. banners and overlays) and VPAID ad unit, the the player is responsible for displaying the ad, firing ad-related events, and beaconing.

Member	Type	Description
apiFramework	String	Indicates the API Framework for the ad (e.g., VPAID). A null value is returned for ads that do not have an API Framework.
companions	Array	List of companion ads that go with the ad. Companion ads are also ad objects.
mimeType	String	Indicates the ad's Internet media type (aka mime-type). Video ad example: uplynk/m3u8 VPAID (JS) example: application/javascript
creative	String	If applicable, indicates the creative to display. Video Ad (CMS): Indicates the asset ID for the video ad pushed from the CMS. Video Ad (VPAID): Indicates the URL to the VPAID JS or SWF.
events	Object	Object containing all of the events for this ad. Each event type will contain an array of URLs. For more information on possible event types, see the VAST 3 specification document. Event names are reported in lower-case.
width	Float	If applicable, indicates the width of the creative. This parameter will report "0" for the width/height of video ads.
height	Float	If applicable, indicates the height of the creative.
duration	Float	Indicates the duration, in seconds, of an ad's encoded video. VPAID: For VPAID ads, this parameter reports the duration returned from the ad server.
extensions	Array	Contains the custom set of VAST extensions returned by the ad server. Each custom extension is reported as an object. Learn more.
fw_parameters	Object	FreeWheel Only If the ad response provided by FreeWheel contains creative parameters, they will be reported as name-value pairs within this object. Learn more about FreeWheel creative parameters.

Placeholder Ads

A placeholder ad is:

A short blank video that serves as a placeholder for non-video ads (i.e., VPAID ads).
A system asset. As such, its asset ID (i.e., bcf072cb69e149f0b3547705b98abfe9) will not correspond to an asset in your CMS library.
Periodically updated to reflect our evolving requirements and therefore its asset ID is subject to change.

When the server comes across an interactive ad, it replaces the ad with the placeholder ad in the m3u8 playlist. Upon encountering a placeholder ad, the client can look up the information about the VPAID ad from the ads response. The placeholderOffsets array contains a list of placeholder objects that hold references to these placeholder ads for convenience.

Parameters	Data Type	Description
startTime	Float	Indicates the starting time of the placeholder ad. This value is in player time for the entire m3u8 timeline.
endTime	Float	Indicates the ending time of the placeholder ad.
breaksIndex	Integer	Indicates the index in the ads.breaks array that contains the VPAID ad that was replaced.
adsIndex	Integer	Indicates the index in the ads.breaks.ads array that identifies the location for VPAID ad information.

If the player supports timed metadata, a client can detect when a placeholder ad is playing through the start/end time and/or the asset ID (i.e., bcf072cb69e149f0b3547705b98abfe9). Upon detecting a placeholder ad, the client can pause the video player, load the information for the VPAID ad, and display the VPAID ad in the player window. Upon detecting a placeholder ad, the client can look in the ads.placeholderOffsets array to locate the offsets in the ads.breaks.ads array for the VPAID ad information.

For example, based off of the following sample response, VPAID ad information may be looked up via the placeholderOffsets array once 9.97 seconds have elapsed.

vpaidAd = ads.breaks[placeholderOffsets[0].breaksIndex].ads[placeholderOffsets[0].adsIndex]

Sample Request/Response

Request:

https://content.uplynk.com/preplay/bbc57167dd9d4ff6924e619195220a30.json?ad=fw&cid=bbc57167dd9d4ff6924e619195220a30&oid=2db76a45e14b44668a8458e27f3a96b4&exp=1406833832&v=2&test=1&rn=1075602717&tc=1&ct=a&sig=0799a3727db220b9f1edb8991e73fb0489fd64956d463fe845b1e231f87cd15c

Response:

{
	"ads": {
		"breakOffsets": [{
				"index": 0,
				"timeOffset": 0.0
			}
		],
		"breaks": [{
				"ads": [{
						"apiFramework": null,
						"companions": [],
						"creative": "99698c4be3fb41efa36a8b4383dba0f8",
						"duration": 9.962666666666665,
						"events": {
							"clickthroughs": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"completes": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"firstquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"impressions": [
								"http://account.v.fwmrm.net/ad/l/1?..."
								"http://sync.adap.tv/sync?type=gif&key;=freewheelmediainc&uid;=a132_6033740266974922981"
							],
							"midpoints": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"thirdquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							]
						},
						"mimeType": "uplynk/m3u8"
					}, {
						"apiFramework": "VPAID",
						"companions": [{
								"adSlotID": "",
								"apiFramework": null,
								"creative": "<IFRAME SRC=\"http://spc--cedgpeifeegfidlecefggfbf-......\"></IFRAME>",
								"duration": 0,
								"events": {},
								"expandedHeight": 0,
								"expanededWidth": 0,
								"height": 60,
								"mimeType": "iframce",
								"width": 300
							}, {
								"adSlotID": "",
								"apiFramework": null,
								"creative": "<IFRAME SRC=\"http://spc--cedgpeifeegfidlecefggfbf-......\"></IFRAME>",
								"duration": 0,
								"events": {},
								"expandedHeight": 0,
								"expanededWidth": 0,
								"height": 250,
								"mimeType": "iframe",
								"width": 300
							}
						],
						"creative": "http://cdn457.telemetryverification.net/tv2n/telemetry_player_vpaid_as3.../"
						"duration": 31.0,
						"events": {
							"clickthroughs": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"completes": [
								"http://account.v.fwmrm.net/ad/l/1..."
							],
							"firstquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"impressions": [
								"http://account.v.fwmrm.net/ad/l/1..."
							],
							"midpoints": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"thirdquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							]
						},
						"mimeType": "application/x-shockwave-flash"
					}, {
						"apiFramework": null,
						"companions": [],
						"creative": "e7261e3a52894cb3927ad22b57632fee",
						"duration": 30.06964583333333,
						"events": {
							"clickthroughs": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"completes": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"firstquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"impressions": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"midpoints": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							],
							"thirdquartiles": [
								"http://account.v.fwmrm.net/ad/l/1?..."
							]
						},
						"mimeType": "uplynk/m3u8"
					}
				],
				"breakId": "0.0.0.918373367",
				"duration": 71.03231249999999,
				"events": {
					"impressions": [
						"http://account.v.fwmrm.net/ad/l/1?..."
					]
				},
				"height": 0.0,
				"position": "preroll",
				"timeOffset": 0.0,
				"type": "linear",
				"width": 0.0
			},
		],
		"placeholderOffsets": [{
				"adsIndex": 1,
				"breaksIndex": 0,
				"endTime": 11.895999999999999,
				"startTime": 9.962666666666665
			},
		]
	}
	"boundaries": [{
			"asset_id": "<asset_id>",
			"content_type": "ad",
			"duration": 33.352,
			"name": "<boundary_name>",
			"offset": 151.39433333333338
		}, {
			"asset_id": "<asset_id>",
			"content_type": "ad",
			"duration": 64.12,
			"name": "<boundary_name>",
			"offset": 544.264684689418916
		}
	],
	"playURL": "https://content-ausw2.uplynk.com/preplay2/1c829785506f46dda4c605abdf65392b/e8245459fbee13bea1eca363922abde1/2UBt6P54fwN5z9aWiBw8Uo63jQoaLUi44rZFBePMZzPd.m3u8?pbs=f6ce286e2ce14b7ba2eade606bd67cb6",
	"interstitialURL": "https://content-ause2.uplynk.com:8000/session/appletvints/4f7da2a661c2499897471a9c922ebd82.xml",
	"prefix": "https://content-ausw2.uplynk.com",
	"sid": "f6ce286e2ce14b7ba2eade606bd67cb6"
}

Features

Enable one or more of the following features via the ad.pingf parameter (Live / VOD):

Feature	Value	Description
Ad Impressions	1	VOD Only Increases the accuracy of ad events by passing the current playback time to Uplynk.
Video Views	2	VOD Only Sends content impressions to the FreeWheel server.
Ad Impressions + Video Views	3	VOD Only Enables both the Ad Impressions and Video Views features. Both of these features are described above.
Linear Ad Data	4	Live Linear Only Includes data in the response for the next ad break. This information is useful when your client requires access to ad-related data during playback (e.g., when handling click events). Do not enable this feature for VOD content. Use the data returned via the Preplay API instead.

Cross-Domain Issues

The Preplay endpoint may leverage JSONP to call a JavaScript function. This is especially useful for environments (e.g., using JavaScript from within a web browser) that restrict the domains to which requests may be directed.

A ".js" file extension is required when using JSONP.

https://content.uplynk.com/preplay/<AssetID>.js?v=2&jsonp=MyFunction

MyFunction({"prefix": "https://content-ausw1.uplynk.com", "ads": {...}, "playURL": "...", ...})

The response also includes header data required for cross-domain requests.