Customer Sign In

upLynk

Preplay API: Version 3

The latest version of the Preplay API is described below.

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

Overview

The purpose of the Preplay method varies by streaming technology.

  • Live Streaming (Live Channel): Retrieves a live channel's playback URL and information required to request the Ping method.
  • Video On-Demand Streaming: Returns ad break information before the start of playback.

Live Streaming (Live Channel)

This method 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 method.
  • The start time and duration of each ad that took place during a given time period.

Tip: Retrieve additional ad information via the Ping method.

Request

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

  • The Preplay API has switched to our "versioned api" URL style, and the "channel" URL segment must be prepended with a "preplay" URL segment.
  • This method uses the json file name extension instead of m3u8.
Request URL syntax:
http://content.uplynk.com/api/v3/preplay/channel/<ChannelID>.json
http://content.uplynk.com/api/v3/preplay/channel/ext/<AccountID>/<ChannelExternaID>.json

Request query string parameters are described below.

ParameterRequiredDescription
tsOptional

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.

endtsOptional

This parameter is only relevant when the request includes the ts parameter.

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.

ad.sssbOptionalDetermines 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)

Important: 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.

Important: 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.

Response

Response body parameters are described below.

ParameterTypeDescription
playURLStringIndicates the playback URL sent to the player.

This playback URL should not be modified.

prefixStringIndicates the zone prefix (e.g. http://content-ause2.uplynk.com/) for the viewer's session. Use this prefix when submitting playback or API requests (e.g., ping method) for this session.
sidStringIndicates a viewer's session ID.
adsArrayContains a list of ads that took place during the time period defined by the ts and endts request parameters.

duration

FloatIndicates the duration, in seconds, of an ad break.

ts

FloatIndicates the start time, in Unix time, of an ad break.

extensions

ArrayVAST 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

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

Example:
{
    'ads': [
         {'duration': 60.293708333333335, 'ts': 1457033271.8485},
         {'duration': 60.4043125, 'ts': 1457034417.0621874},
         {'duration': 60.0268125, 'ts': 1457037981.8656042}
    ],
    'playURL': 'http://content-ause2.uplynk.com:8000/preplay2/channel/7ac2f0d27d4b929643652de654e2b8/f528764d644d212b3c21fbca0cb8d6/6K9u6kRTD54aInrt32DnNMVtJs2br2rrHTOY2.m3u8?pbs=bcb82775835b98b36d0a1a73100eaa',
    'prefix': 'http://content-ause2.uplynk.com:8000',
    'sid': 'bcb82775835b98b36d0a1a73100eaa'
}

On-Demand Streaming

The request URL for this method is similar to the asset playback URL defined in the Generating playback URLs article. The main differences between these URLs are:

  • The Preplay API has switched to our "versioned api" URL style.
  • This method uses the json file name extension instead of m3u8.
Request URL syntax:
http://content.uplynk.com/api/v3/preplay/<assetID>.json
http://content.uplynk.com/api/v3/preplay/ext/<AccountID>/<ExternaID>.json

All playback parameters, including the token signature, should be sent with the Preplay URL.

Sample Preplay URL:

http://content.uplynk.com/api/v3/preplay/bbc57167dd9d4ff6924e619195220a30.json?ad=fw&cid=bbc57167dd9d4ff6924e619195220a30&oid=2db76a45e14b44668a8458e27f3a96b4&exp=1406833832&test=1&rn=1075602717&tc=1&ct=a&sig=0799a3727db220b9f1edb8991e73fb0489fd64956d463fe845b1e231f87cd15c

Request Query String Parameters

ParameterRequiredDescription
jsonpOptionalDefines the name of the JavaScript function call that will wrap the response.

Note: The file name extension for this value must be ".js."

ad.sssbOptionalDetermines 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)

Important: 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.

Important: 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.

Preplay Response

The Preplay API returns a JSON response containing the session ID for the viewer, the playback URL, the zone prefix (required when requesting the Ping method), and ad information.

ParameterTypeDescription
sidStringIndicates a viewer's session ID.
prefixStringIndicates the zone prefix (e.g. http://content-ause2.uplynk.com/) for the viewer's session. Use this prefix when submitting playback or API requests (e.g., ping method) for this session.
playURLStringIndicates the playback URL sent to the player.

This playback URL should not be modified.

adsObjectContains ad information, such as break offsets and non-video ads. Information on the ads object is provided below.
interstitialURLStringIndicates the URL to the XML file containing interstitial information for Apple TV. This parameter reports null when ads are not found.
Example Preplay response. (This example is referenced below.)
  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
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
{
    "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": "http://content-ausw2.uplynk.com/preplay2/1c829785506f46dda4c605abdf65392b/e8245459fbee13bea1eca363922abde1/2UBt6P54fwN5z9aWiBw8Uo63jQoaLUi44rZFBePMZzPd.m3u8?pbs=f6ce286e2ce14b7ba2eade606bd67cb6",
    "interstitialURL": "http://content-ause2.uplynk.com:8000/session/appletvints/4f7da2a661c2499897471a9c922ebd82.xml",
    "prefix": "http://content-ausw2.uplynk.com",
    "sid": "f6ce286e2ce14b7ba2eade606bd67cb6"
}

Ads Object

This section explains the ads object returned by the Preplay method.

Ads object propertiesTypeDescription
breaksArrayA 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.

breakOffsetsArrayA 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.
placeholderOffsetsArrayA list of objects with start and end times for every non-video ad that has been replaced with a short blank video. The placeholder asset ID for non-video ads will always be "a18c2e3fd9104d84a829e5ec475de917." Additional information is provided below.

Ad Break (breaks) Object

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

NameTypeDescription
eventsObjectContains events for the ad break.
ArrayA list of ad objects associated with this ad break.
typeStringIndicates the ad break type. Possible values are linear or nonlinear. See VAST 3.0 document for more information.
positionStringIndicates the position of the ad break. Possible values are preroll, midroll, postroll, pause, and overlay.
timeOffsetFloatIndicates the start time of the ad break in the player timeline.
durationFloatIndicates 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 (ads) 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.0 specification document.

Important: 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.

NameTypeDescription
apiFrameworkStringIndicates the API Framework for the ad.
Sample values:
  • VPAID: VPAID
  • No API Framework: A null value will be returned.
companionsArrayList of companion ads that go with the ad. Companion ads are also ad objects.
mimeTypeStringIndicates the ad's Internet media type (aka mime-type).
Sample values:
  • Video Ads: uplynk/m3u8
  • VPAID (JS): application/javascript
creativeStringIf 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.
eventsObjectObject 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.0 document.

Note: Event names are reported in lower-case.

widthFloatIf applicable, indicates the width of the creative. This parameter will report "0" for the width/height of video ads.
heightFloatIf applicable, indicates the height of the creative.
durationFloatIndicates the duration, in seconds, of an ad's encoded video.

VPAID: For VPAID ads, this parameter reports the duration returned from the ad server.

extensionsArrayContains the custom set of VAST extensions returned by the ad server. Each custom extension is reported as an object.

Learn more.

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

adParametersStringVAST Only: Addtional data to be passed into the video ad. Refer to the VAST spec for more information.

Placeholder Ads

The placeholder ad is a short blank video that serves as a placeholder for non-video ads (i.e., VPAID ads). When the server comes across an interactive ad, it replaces the ad with the placeholder ad in the m3u8 playlist. When the client comes across the asset with the placeholder asset ID, the client can look up the information about the VPAID ad from the ads response. The placeholderOffsets array contains a list of objects that hold references to these placeholder ads for convenience.

NameTypeDescription
startTimeFloatIndicates the starting time of the placeholder ad. This value is in player time for the entire m3u8 timeline.
endTimeFloatIndicates the ending time of the placeholder ad.
breaksIndexIntegerIndicates the index in the ads.breaks array that contains the VPAID ad that was replaced.
adsIndexIntegerIndicates 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 assetID (a18c2e3fd9104d84a829e5ec475de917). 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.

The following sample scenario uses the above sample response. Once 9.97 seconds have elapsed, VPAID ad information may be looked up via the placeholderOffsets.

vpaidAd = ads.breaks[placeholderOffsets[0].breaksIndex].ads[placeholderOffsets[0].adsIndex]

Cross-domain issues

The Preplay method 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.

Note: A ".js" file name extension is required when using JSONP.

http://content.uplynk.com/preplay/<assetID>.js?v=2&jsonp;=MyFunction
MyFunction({"prefix": "http://content-ausw1.uplynk.com", "ads": {...}, "playURL": "...", ...})

The response also includes header data required for cross-domain requests.