The Ping 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 viewer seeks to a new position.
Pass the seek event whenever the viewer seeks to a new position.
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:
Pass the zone URL prefix and the ID for the current playback session when requesting this endpoint. Retrieve this information through the Preplay endpoint.
Indicate the set of features that will be supported for this playback session by adding the ad.pingf={Value} parameter to the playback token.
Learn more.
Request syntax:
Pass the following request parameters:
| Parameter | Description |
|---|---|
|
Required |
Determines which version of this endpoint will be requested. Valid values are:
|
|
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. |
|
An event should only be passed when playback starts or when a viewer seeks to a new position. Valid values are:
|
|
|
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. |
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.
|
|
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.
Learn more.
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"}
...
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 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:
{
"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>"
}
]
}
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
}
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.
Request:
http://content-ausw4.uplynk.com/session/ping/c98031abff2649cfbc2f00ef2f982716.json?v=3&ev=start&pt=0
Response:
{
"next_time": 2.49066
}