User Guides

Client-Side Beaconing Using Dynamic Manifest Markers

Suggest Edits

Uplynk supports server-side ad beaconing for ads inserted via Server-Side Ad Insertion (SSAI). When client-side ad beaconing was desired, historically this was done using the Uplynk Ping API. However, now Uplynk recommends using Dynamic Manifest Markers for doing this.

Dynamic Manifest Markers (DMMs) place information about ad breaks and beaconing information directly in the streaming manifest rather than using additional API calls. This works for both VOD and linear content to support client-side ad beaconing.

Client-Side Beaconing Using Dynamic Manifest Markers

PreplayV2 DMM

To enable raw URLs for the client to fire for ad beacons in DMMs, the following parameter needs to be added to the Uplynk URL:
ad.timedmeta=1

This DMM is referred to as the PreplayV2 DMM since it provides information similar to what is contained in the Preplay version of the Uplynk URL. The dmm.beacons.ads=quartiles parameter could be used if only quartile information is required.

When client-side beaconing is used, server-side ad beaconing has to be disabled by adding this parameter to the Uplynk URL:
ad.sssb=1

The ad.timedmeta=1 and ad.sssb parameters work for both VOD and linear modes of operations for Uplynk Streaming.

Break Info DMM

To get ad and ad break information, use the Break Info DMM by including the URL parameter:
dmm.schema.ads=break_info

This parameter will include things such as break and ad duration, break and ad index, number of ads in the current break, etc. This is documented at Ads.

DMM Schema

PreplayV2 DMM

Use the ad.timedmeta=1 URL parameter to include the beaconing DMM into your manifest.

Example:
https://content.uplynk.com/585f5a45f46c4fbc888e09d533878d54.mpd?ad=mock&ad.timedmeta=1

Schema:

{
  "_duration": 0,			The duration in seconds of the ad
  "adID": "",				Ad identifier
  "adUnit": "",
  "api": "",
  "companions": [],			List of companion ads that go with the ad
  "creative": "",			If applicable, indicates the creative to display
  "creativeID": "",			Identifier of the creative to display
  "customer_events": {		Events for this ad
    "impressions": [...],		Each event type contains an array of URLs
    "midpoints": [...],
    ...
  },
  "duration": 0, 			The duration in seconds of the ad
  "events": {				Events for this ad (used for AdProxy)
    "impressions_pks": [...],	Each event type contains an array of pks
    "midpoints_pks": [...],
    ...
  },
  "extensions": [...],		Custom set of VAST extensions returned by the ad server
  "fw_parameters": {},		FreeWheel only, creative params name-value pairs
  "height": 0,			If applicable, indicates the height of the creative
  "mimeType": "",			Indicates the ad's Internet media type
  "omsdk_id": "",			Open Measurement SDK identifier
  "width": 0				If applicable, indicates the width of the creative
}

Sample:

{
  "_duration": 6.144,
  "adID": "9000084",
  "adUnit": "",
  "api": "",
  "companions": [],
  "creative": "f7cd47d988ae46d7b5d11e034937691b",
  "creativeID": "9000084",
  "customer_events": {
    "clickthroughs": [
  "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=d8a605b1-546f-4754-9c6d-277336014384&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=ClickThrough"
    ],
    "clicktrackings": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=b523a2d9-24b2-42e8-b92f-dc765390cbb6&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=ClickTracking"
    ],
    "completes": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=1f109b24-1125-444b-9912-c316c44e5e14&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=complete"
    ],
    "firstquartiles": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=a834b195-10a6-4ae8-a1c3-94e48ef88842&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=firstQuartile"
    ],
    "impressions": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=1b833dd2-26bd-4d2e-ac9a-de794ffab2f4&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=impression1",
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=4da0fc39-326e-4acd-b593-b071f1fd3033&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=start"
    ],
    "midpoints": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=44e4db28-2dc0-4b99-bb18-bc93c5b7e4ff&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=midpoint"
    ],
    "thirdquartiles": [
      "https://mockbeacons.downlynk.net/record-impression/?adId=9000084&ads_type=gam&campaign=mock-gam-fallback&creativeId=9000084&guid=e9693ad1-9e81-45bb-b170-17df44e794d1&origin=initial&response_guid=705b4f4e-7442-4efe-91a4-906808d718c6&tracker=thirdQuartile"
    ]
  },
  "duration": 6.144,
  "events": {
    "clickthroughs_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--clickthroughs-0"
    ],
    "clicktrackings_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--clicktrackings-0"
    ],
    "completes_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--completes-0"
    ],
    "firstquartiles_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--firstquartiles-0"
    ],
    "impressions_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--impressions-0",
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--impressions-1"
    ],
    "midpoints_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--midpoints-0"
    ],
    "thirdquartiles_pks": [
      "d0bfc96a-d97a-4925-8e67-17ad063bdd80-0-0--thirdquartiles-0"
    ]
  },
  "extensions": [
    {
      "AdVerifications": [
        {
          "AdVerifications": [
            {
              "Verification": [
                {
                  "JavaScriptResource": "https://s3-us-west-2.amazonaws.com/omsdk-files/compliance-js/omid-validation-verification-script-v1.js",
                  "apiFramework": "omid",
                  "browserOptional": "true"
                },
                {
                  "VerificationParameters": "iabtechlab"
                }
              ],
              "vendor": "iabtechlab.com-omid"
            }
          ]
        }
      ]
    },
    {
      "activeview": [
        {
          "CustomTracking": [
            {
              "Tracking": [],
              "event": "abandon"
            },
            {
              "Tracking": [],
              "event": "viewable_impression"
            }
          ]
        }
      ]
    },
    {
      "geo": [
        {
          "Bandwidth": "4"
        },
        {
          "BandwidthKbps": "20000"
        },
        {
          "Country": "US"
        }
      ]
    },
    {
      "metrics": [
        {
          "AdEventId": "2d678a2546fe69d04763c5f5"
        },
        {
          "FeEventId": "2d678a2546fe69d04763c5f5"
        }
      ]
    },
    {
      "waterfall": [
        {
          "fallback_index": "0"
        }
      ]
    }
  ],
  "fw_parameters": {},
  "height": 720,
  "mimeType": "uplynk/m3u8",
  "omsdk_id": "3beaecb8101842e1b5dd2040ac803ef2",
  "width": 1280
}

HLS

The DMM is presented in the child manifests within the X-DATA field of #EXT-X-DATERANGE tags that can be identified by the "urn:uplynk:ad-data:break_info" class, as follows:/

#EXT-X-DATERANGE:ID="581cd8d9f2d9444a9174f8295d8072a1:0:0:break_info:ads",START-DATE="2023-09-11T23:29:04.655000+00:00",DURATION=15.1623,CLASS="urn:uplynk:ad-data:break_info",X-DATA="eyJhZF9kdXIiOiAxNS4xNjIzLCAiYWRfaW5kZXgiOiAwLCAiYWRfb2Zmc2V0IjogMC4wLCAiYWRfc2xhdGUiOiAwLCAiYnJlYWtfZHVyX2FjdCI6IDMwLjIwMjMsICJicmVha19kdXJfcmVxIjogMzcuNjc0NjY2NjY2NjY2NjcsICJicmVha19pbmRleCI6IDAsICJkbW1fZGF0YV9ub3RfcmVhZHkiOiAwLCAibnVtX2FkcyI6IDIsICJpZCI6ICI1ODFjZDhkOWYyZDk0NDRhOTE3NGY4Mjk1ZDgwNzJhMTowOjA6YnJlYWtfaW5mbzphZHMiLCAiY2xhc3MiOiAidXJuOnVwbHluazphZC1kYXRhOmJyZWFrX2luZm8iLCAic3RhcnREYXRlIjogIjIwMjMtMDktMTFUMjM6Mjk6MDQuNjU1MDAwKzAwOjAwIiwgImR1cmF0aW9uIjogMTUuMTYyM30="

Here a sample of an X-DATA field base64-decoded for the Break Info DMM:

{
   "ad_dur":15.1623,
   "ad_index":0,
   "ad_offset":0.0,
   "ad_slate":0,
   "break_dur_act":30.2023,
   "break_dur_req":37.67466666666667,
   "break_index":0,
   "dmm_data_not_ready":0,
   "num_ads":2,
   "id":"581cd8d9f2d9444a9174f8295d8072a1:0:0:break_info:ads",
   "class":"urn:uplynk:ad-data:break_info",
   "startDate":"2023-09-11T23:29:04.655000+00:00",
   "duration":15.1623
}

DASH

A Break Info DMM is added to the manifest in an EventStream with a schemeIdUri="urn:uplynk:ad-data:break_info" like:

<EventStream schemeIdUri="urn:uplynk:ad-data:break_info" timescale="90000" value="ad-data">
<Event duration="2706253" id="9281250" presentationTime="0">
{
"ad_dur":30.069479166666678,
"ad_index":0,
"ad_offset":0.0,
"ad_slate":0,
"break_dur_act":30.069479166666678,
"break_dur_req":0.0,
"break_index":0,
"dmm_data_not_ready":0,
"num_ads":1
}
</Event>
</EventStream>

The EventStream for this DMM only has one Event, and only occurs inside Ad Periods.

PreplayV2 and Break Info DMMs in DASH

  • The PreplayV2, and the Break Info DMMs have their own EventStream each
  • Each EventStream only has one Event
  • PreplayV2 and Break Info EventStreams only occur inside Ad Periods, which can be identified through its AssetIdentifier, schemeIdUri="urn:com:uplynk:ad-asset-id"
  • An Ad Period can have a combination of PreplayV2 and Break Info EventStreams
  • For Linear, the DMMs flow into the manifest when an ad break is approaching, and get included in the mpd during the live window

PreplayV2 and Break Info DMMs in HLS

The following #EXT-X-DATERANGE fields are duplicated into the base64-encoded information presented in the X-DATA field, and mapped as described below:

# EXT-X-DATERANGEDMM
IDid
DURATIONduration
CLASSclass
START-DATEstartDate

Take for example the following VOD asset that has four ad breaks. Linear playback follows the same logic.

When the asset is played with URL params to include both, the PreplayV2, and the Break Info DMMs as the URL below:

https://content.uplynk.com/7fdef903b77e41e2b4fff438c326b2e9.m3u8?ad=dummy&ad.timedmeta=1&dmm.schemas.break=break_info

The manifests served include both the PreplayV2 and the Break Info DMMs for every ad. The DMMs are presented after #EXT-X-DISCONTINUITY tags, and before ad segments.

For this example, the four Ad Breaks are being filled with six ads as follows:

  • Ad Break 1 @ 00:00:50
    • {"ad_index": 0, "break_index": 0, "num_ads": 2}
    • {"ad_index": 1, "break_index": 0, "num_ads": 2}
  • Ad Break 2 @ 00:01:42
    • {"ad_index": 0, "break_index": 1, "num_ads": 1}
  • Ad Break 3 @ 00:02:44
    • {"ad_index": 0, "break_index": 2, "num_ads": 2}
    • {"ad_index": 1, "break_index": 2, "num_ads": 2}
  • Ad Break 4 @ 00:03:30
    • {"ad_index": 0, "break_index": 3, "num_ads": 1}

Updated 4 days ago