Customer Sign In

upLynk

Ping API: Version 2

Version 2 of the Ping API is described below. The latest version of the Ping API is version 3.

Note: It is our recommendation to update existing applications to version 3 of the Ping API. However, version 2 of the Ping API is still supported.

Overview

The Ping method allows the player to provide its current time, triggered events, and playhead updates to Uplynk servers. In turn, our servers will respond with:

  • The subsequent time at which the player should submit another request to this method.
  • Live/Linear Streaming Only: Information about upcoming ads.

Usage

Call this method by passing the ID for the current playback session and the zone URL prefix. Retrieve this information through the Preplay method prior to calling this method.

API Format
http://<zone prefix>.uplynk.com/session/ping/<session ID>.json?v=3&pt=<current player time>&ev=<event>
Example Call
http://content-ausw4.uplynk.com/session/ping/c98031abff2649cfbc2f00ef2f982716.json?v=3&ev=start&pt=0

In addition to calling the API when the player reaches the next time, the player also needs to call the API anytime that the viewer seeks to a new position. In this case the player will pass the 'seek' event into the API

Ping API parameters

ParameterRequiredDescription
v YES Current version of the API. This value should always be '2.'
pt YES Current player time, in seconds. This must always be passed in the call. Example: If the player is at 1min 22s, this value will be 82.
ev NO Event that triggered the API call if applicable. Possible values are 'seek' and 'start'.
ft NO* From Time. The player time (in seconds) at the moment the user clicks somewhere else on the timeline. *Requred if ev == 'seek' AND you want to send Freewheel Video Views (see the Video Views section in the Freewheel Integration documentation.)

Events

When the player starts playback the client should immediately make a call to the API and pass ev=start (along with pt=0). This lets the server know where the view starts and allows the server to fire any starting events if necessary.

It is also necessary to make the ping call anytime that the viewer seeks, using ev=seek. The server needs to reset its timeline in these cases so it does not inadvertently fire events for ads that have been skipped. For all other calls no event needs to be passed to the server.

Ping API Response

The response from the server will contain the next time that the player should make the call again. The next time is in player time, meaning the client should call the ping API again when the player reaches that time.

ParameterTypeDescription
next_timefloatThe next time the client should make the API call (in player time). If this value is -1 the client does not need to make any more API calls.
adsObjectContains information about upcoming ads.
  • FreeWheel Ad Server: Contains FreeWheel creative parameters.
    Learn more.
  • VPAID: Contains VPAID ads.
extensionsArrayVAST Only: Contains the custom set of VAST extensions returned by the ad server. Each custom extension is reported as an object.

Learn more.

errorstringError description if one occurs. If no error is present this property is missing
Example Response
1
{"next_time": 2.49066}

Responses for subsequent player requests may include additional data (e.g., linear or VPAID ads).

Learn more about Ping features.

FreeWheel Creative Parameters

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "next_time": 60.01,
  "ads": {
    "breaks": [
      {
        "breakId": "mid",
        "ads": [
          {
            "fw_parameters": {"_fw_creative_name": "Sample Creative Name", "_fw_campaign_name": "Sample Campaign Name"}
		  ...

Learn more about FreeWheel creative parameters.

Enabling the 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. If you attempt to call the API without passing in the ad.cping parameter you can throw off the server's ability to make ad event calls correctly.

In addition to enabling the API, you must also notify the server of the features you want to support for this viewing session. To specify which features you'd like to enable, you add the ad.pingf={some value} parameter to the playback token. Instructions for calculating the value to pass are given below in the features section.

Example Playback URL with cping
http://content.uplynk.com/preplay/cc829785506f46dda4c605abdf65392b.json?ad=adserver&ad.cping=1&ad.pingf=3

Ping API Features

Version 3 of the API introduces the ability to request specific features be turned on or off, and requires at least one feature be explicitly enabled.

FeatureValueDescription
Ad Impressions 1 When the ping API's ad impressions features is enabled, the current player time passed from the client to the server will help increase the accuracy of ad events.
Video Views 2 FreeWheel's Video View by Callback feature. Used to send content impressions to the FreeWheel server.
Linear Ad Data 4 Enable this feature for live/linear content if your client needs to access ad-related data during playback (for example, to handle CLICK events). The API will return an object containing data for the next upcoming ad break. Don't enable this feature for VOD content; instead use the data returned via the Preplay API.

Calculating the pingf Parameter

The value to pass in the ad.pingf parameter is simply the sum of the values for the features you want to enable. For example, if I wanted to enable both Ad Impressions (value of 1) and Video Views (value of 2), I'd pass ad.pingf=3. If I wish to only enable Video Views, I'd pass ad.pingf=2.

Return Values for Features

As noted above, all features will at minimum return next_time, which is a value that notes the time in seconds at which the player should contact the ping API again. In addition, some features will return additional data that is useful for the client. Possible values for these are given below:

Linear Ad Data Return Value

This feature will return an ads object similarly to what's returned in VOD preplay requests. 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. If the duration of the break is unknown (see note below) then this member will be omitted.

A response with the ads object, when breakEnd is known will look similar to this:

Example response with Linear Ad Data enabled. breakEnd is known when ads object is sent:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  "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>"
    }
  ]
}

A note about the break end time

In cases where the player arrives at an ad break whose duration is unknown, upLynk will request 240 seconds of ads by default. As such, the duration member shouldn't be relied upon to calculate when the break will end. There are scenarios where upLynk will request more ads than will be inserted into the stream.

For example:You issue a /pod_start slicer API command, and 120 seconds later issue the accompanying /pod_end command. By default, live channels trail the live horizon by 60-75 seconds. This means that when the player arrives at the start of the ad break (~60s after /pod_start) the /pod_end hasn't been issued yet. upLynk needs to request ads and receive the response before the player arrives at the ad break, so if the system doesn't know how long the break will be, it will request a default of 240 seconds (4 minutes) of ads.

In this example, we request and receive 240 seconds of ads for a 120 second break. The ads object in the ping response will contain all 240s worth of ads, and because the system doesn't know the end time of the break, this response will not include a breakEnd. In these cases, the end of the break will be returned separately in the response to subsequent pings. Break end times returned separately from the ads object will be specified as currentBreakEnd

Example response when breakEnd is sent subsequently in a separate response
1
2
3
4
{
  "next_time": 60.01,
  "currentBreakEnd": 90.12
}

VPAID Ad Units

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

Learn more about: