The Ping v2 endpoint allows the player to provide its current time, triggered events, and playhead updates to our system. In turn, our system will respond with the subsequent time (i.e., playback position) at which the player should submit another request to this endpoint.

This endpoint also returns information about upcoming ads when requesting information for a live/linear stream.

Call this endpoint when:

The player reaches the next playback position at which a request to this endpoint is expected.
The viewer seeks to a new position.

Pass the seek event (ev in the parameter table below) whenever the viewer seeks to a new position.

Enabling the Ping API

By default, the Ping API is disabled for all sessions. To enable it, the ad.cping=1 parameter must be added to the playback token of your Preplay request.

Attempting to request this endpoint without passing the ad.cping parameter to the Preplay endpoint may adversely affect ad event calls.

Sample Preplay request (VOD) with the ad.cping parameter:

https://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1

Request

Pass the zone URL prefix and the ID for the current playback session when requesting this endpoint. Retrieve this information through the Preplay request.

Indicate the set of features that will be supported for this playback session by adding the ad.pingf={Value} parameter to the playback token.

Request syntax:

http://ZonePrefix.uplynk.com/session/ping/SessionID.json?v={Version}&pt=CurrentPlayerTime&ev=Event

Pass the following request parameters:

Parameter	Description
v Required	Determines which version of this endpoint will be requested. Valid values are: 2 3: Recommended. Use version 3 when you have enabled one or more of the following features via the Preplay API's ad.pingf parameter: ad impressions, video views, and linear ad data.
pt Required	Indicates the current playback position in seconds. Example: If the player is currently at the 1 minute and 22 second mark, then this parameter should be set to 82.
ev	An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are: start: Pass this event, along with pt=0, when the player start playback. This lets the server know where playback starts and allows the server to fire start events as needed. seek: Pass this event when a viewer seeks. This resets the timeline to prevent inadvertently firing events for skipped ads.
ft	Indicates the playback position, in seconds, right before a viewer seeks to a different position in the timeline. This parameter is required for seek events when sending a FreeWheel Video View.

Response

The response for a successful request may contain the following parameters:

Parameter	Description
next_time	Indicates the next playback position, in seconds, at which the player should request this endpoint. The player should not issue additional API requests when this parameter returns -1.0.
ads	Contains information about upcoming ads. FreeWheel Ad Server: ContainsFreeWheel creative parameters. VPAID: Contains VPAID ads.
extensions	VAST Only Contains the custom set of VAST Extensions returned by the ad server. Each custom extension is reported as an object.
error	Error Response Only Describes the error that occurred.

Responses for subsequent player requests may include feature-specific data, such as linear ad data or VPAID ads.

FreeWheel Creative

FreeWheel may include creative parameters with an ad response. These parameters will be included within the response sent to the client.

In the following sample response, notice that the fw_parameters contains 2 FreeWheel creative parameters.

{
  "next_time": 60.01,
  "ads": {
    "breaks": [
      {
        "breakId": "mid",
        "ads": [
          {
            "fw_parameters": {"_fw_creative_name": "Sample Creative Name", "_fw_campaign_name": "Sample Campaign Name"}
		  ...

Linear Ad Data

The Linear Ad Data feature returns an ads object similar to the VOD Preplay API response. This object loosely follows the structure and naming conventions of VMAP 1.0 with VAST 3.0. The breaks member of this object will have only one item which represents the next ad break in the linear stream. Along with timeOffset, which is start time of the ad break in the player's timeline, the break object may also have a member called breakEnd, which is the time the break ends. This member will be omitted when the duration of the ad break is unknown.

The following sample response assumes that:

The Linear Ad Data feature has been enabled.
The duration of the ad break is known.

{
	"next_time": 60.01,
	"ads": {
		"breaks": [{
				"breakId": "mid",
				"ads": [{
						"mimeType": "uplynk/m3u8",
						"apiFramework": null,
						"companions": [],
						"creative": "a2ea6250b6a84d34bff6e866a740dfc1",
						"width": "640",
						"duration": 30.113395833333,
						"height": "266",
						"events": {
							"firstquartiles": ["http://account.v.fwmrm.net/ad/l/1?..."],
							"GENERIC": "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?..."],
							"impressions": [
								"http://account.v.fwmrm.net/ad/l/1?...",
								"http://tags.bluekai.com/site/...",
								"http://dpm.demdex.net/..."
							],
							"completes": ["http://account.v.fwmrm.net/ad/l/1..."],
							"clickthroughs": ["http://account.v.fwmrm.net/ad/l/1?..."]
						}
					},
					// ... more ads here ...
				],
				"duration": 90.183041666667,
				"height": 0,
				"width": 0,
				"timeOffset": 47.47,
				"breakEnd": 77.53,
				"position": "midroll",
				"type": "linear",
				"events": {
					"impressions": [
						"http://account.v.fwmrm.net/ad/l/1..."
					]
				}
			}
		]
	},
	"boundaries": [{
			"offset": 252.663,
			"feature": "ignore_as_ad",
			"name": "<boundary_name>"
		}, {
			"duration": 15.765333333333334,
			"feature": "ignore_as_ad",
			"name": "<boundary_name>"
		}
	]
}

Unknown breakEnd Time

By default, our system will request 240 seconds of ads when a player arrives at an ad break with an unknown duration.

Our system may request more ads than will be inserted into the stream. Therefore, you should not rely on the duration member to calculate when an ad break will end.

For example, you may issue issue a /pod_start command and 120 seconds later issue the accompanying /pod_end command. By default, live channels trail the live horizon by 60 to 75 seconds. This means that when the player arrives at the start of the ad break, approximately 60 seconds after /pod_start, the /pod_end command hasn't been issued yet. However, our system needs to request ads and receive the response before the player arrives at the ad break. Since the ad break's duration is unknown, our system will request a default of 240 seconds (4 minutes) of ads.

In this example, 240 seconds of ads are requested for a 120 second break. The ads object in the Ping response will contain all 240 seconds of ads and will omit the breakEnd member since the end time for the ad break is unknown. Subsequent Ping requests will indicate the ad break's end time via the currentBreakEnd parameter.

Sample response that illustrates how an ad break's end time is reported via subsequent Ping requests:

{
	"next_time": 60.01,
	"currentBreakEnd": 90.12
}

VPAID Ad Units

Once VPAID has been initialized on a session, the Ping endpoint will return an ads object similar to the one returned by the Preplay endpoint for on-demand streaming. This object contains data that describes VPAID ads.

Sample Request/Response

Request:

http://content-ausw4.uplynk.com/session/ping/c98031abff2649cfbc2f00ef2f982716.json?v=3&ev=start&pt=0

Response:

{
	"next_time": 2.49066
}