Preplay API (Version 2)

Use the Preplay endpoint to:

Live Streaming (Live Channel)

This endpoint returns the following type of information:

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[-z].uplynk.com/preplay/channel/<ChannelID>.json

https://content[-z].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:

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.

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[-z].uplynk.com/preplay/<AssetID>.json

https://content[-z].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.

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.

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:

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[-z].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[-z].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.