Preplay v2

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/.json

https://content.uplynk.com/preplay/channel/ext//.json

How is this endpoint different from the playback URL?

The request URL for this endpoint is similar to the live channel playback URL defined in the Playback URLs article. The main differences between these URLs are:

• This endpoint contains an additional URL segment (i.e., /preplay/).
• This endpoint uses the json file extension instead of m3u8.

Pass the following query string parameters:

Response

The response for a successful request contains the following parameters:

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/.json

https://content.uplynk.com/preplay/ext//.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:

Response

The response for a successful request contains the following parameters:

Ads Object

An ads object contains the following members:

Ad Break (breaks) Object

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

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.

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.

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):

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