User Guides

Client-Side Beaconing Using Dynamic Manifest Markers

Fire ad beacons from the client using Dynamic Manifest Markers embedded in the streaming manifest.

Uplynk supports server-side ad beaconing for ads inserted via Server-Side Ad Insertion (SSAI). When client-side ad beaconing is desired, Uplynk recommends using Dynamic Manifest Markers (DMMs).

DMMs place ad break and beaconing information directly in the streaming manifest, eliminating the need for additional API calls. This approach works for both VOD and linear content.

Client-Side Beaconing Using Dynamic Manifest Markers

PreplayV2 DMM

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

This is referred to as the PreplayV2 DMM because it provides information similar to what the Preplay version of the Uplynk URL contains. Use the dmm.beacons.ads=quartiles parameter if only quartile information is required.

When using client-side beaconing, you must disable server-side ad beaconing 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 operation.

Break Info DMM

To retrieve ad and ad break information, use the Break Info DMM by including the following URL parameter:
dmm.schemas.break=break_info

This parameter provides details such as break and ad duration, break and ad index, and number of ads in the current break. For more information, see Ads.

DMM Schema

PreplayV2 DMM

Use the ad.timedmeta=1 URL parameter to include the beaconing DMM in 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 appears in child manifests within the X-DATA field of #EXT-X-DATERANGE tags identified by the "urn:uplynk:ad-data:break_info" class:

#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="

The following is a sample 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

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

<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 contains only one Event and only occurs inside Ad Periods.

PreplayV2 and Break Info DMMs in DASH

  • The PreplayV2 and Break Info DMMs each have their own EventStream.
  • Each EventStream contains only one Event.
  • PreplayV2 and Break Info EventStreams only occur inside Ad Periods, which you can identify through the AssetIdentifier with schemeIdUri="urn:com:uplynk:ad-asset-id".
  • An Ad Period can contain a combination of PreplayV2 and Break Info EventStreams.
  • For linear content, the DMMs flow into the manifest when an ad break is approaching and are 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 in the X-DATA field and mapped as described below:

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

The following example uses a VOD asset with four ad breaks. Linear playback follows the same logic.

VOD asset ad break list showing the time offset, type and duration of breaks inserted during slicing

When you play the asset with URL parameters to include both the PreplayV2 and Break Info DMMs:

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

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

In this example, the four ad breaks are 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}
Start of an HLS VOD manifest through the first ad break, showing the PreplayV2 and Break Info DMM tags for the first ad HLS manifest excerpt showing the PreplayV2 and Break Info DMM tags for the second ad in a break, followed by its media segments HLS manifest excerpt for an ad break showing the PreplayV2 and Break Info DMM tags with their base64 X-DATA payloads HLS manifest excerpt for an ad break filled with two ads, showing the PreplayV2 and Break Info DMM tags for the first ad followed by the second ad's PreplayV2 tag HLS manifest excerpt showing the Break Info DMM for the second ad in a break, followed by its media segments End of the HLS manifest showing the PreplayV2 and Break Info DMM tags for the final ad break, closing with EXT-X-ENDLIST

Updated 23 days ago

Did this page help you?