View as Markdown

Bid Click Tracking (Experimental)

Experimental. This feature is new and may change in any Prebid.js release, including its configuration, events and behavior. Click counts from bidClick, bidClickInferred and ad server click URLs requested by fireTrackers are not expected to match the counts of the ad server, the bidder or other click trackers exactly. See Why Click Counts Differ.

Overview

Since Prebid.js 11.50, Prebid can observe clicks on the banner and native creatives it renders, on mobile and desktop. Observed clicks can emit bidClick events and be reported to the ad server. Banner events are limited to one per bid; native events are also deduplicated per bid by default, unless dedupeNativeClicks: false is set. These events are not a count of every individual click. This serves two setups:

  • GAM with the dynamic creative: register Prebid clicks in Google Ad Manager. The dynamic creative (creative.html) passes GAM’s %%CLICK_URL_UNESC%% click URL to Prebid. With fireTrackers: true, Prebid requests that URL when it observes a click on the winning creative, so GAM can count the click on the Prebid line item.
  • The ad server bids into Prebid: when Prebid chooses the winner and renders it, no ad server creative counts clicks. bidClick gives analytics adapters, including the ad server’s own analytics, a click event for the winning bid. pbjs.renderAd can also take the ad server’s click URL as clickThrough, which fireTrackers requests.

Click observation is for creatives rendered by Prebid.js itself: the dynamic creative and pbjs.renderAd. It is not intended to work with the Prebid Universal Creative, which only receives minimal maintenance. For browser-only Prebid.js line items, use the dynamic creative to enable this behavior. If a PUC line item is shared with AMP or Prebid Mobile inventory, split the browser-only traffic into a separate line item first; the dynamic creative cannot render those other environments.

Configuration

Observed clicks are handled by Prebid.js core when bidClickTracking.enabled is set. Include the bidClickTracking module in your build only if you also want the desktop fallback.

pbjs.setConfig({
  bidClickTracking: {
    enabled: true,
    fireTrackers: true // GAM: request the creative's click URL on each observed click
  }
});

pbjs.onEvent('bidClick', ({ adId, adUnitCode, bidder, method }) => {
  // method is 'creativeClick' (banner) or 'nativeClick'
});
Name Type Default Description
enabled Boolean false Observe clicks and emit bidClick events.
fireTrackers Boolean false Request the ad server click URL (clickUrl from the dynamic creative, or clickThrough passed to pbjs.renderAd) on an observed banner click.
desktopFallback Boolean false Requires the bidClickTracking module. On desktop, infer clicks on creatives whose clicks can’t be observed, and emit bidClickInferred.
dedupeNativeClicks Boolean true Emit bidClick for native clicks once per bid. Set false to emit it for every native click. Bidder click trackers fire on every click either way.

How It Works

  • Banner: for markup (ad) rendered by Prebid, Prebid listens inside the creative’s iframe for trusted clicks on links (<a href>, <area href>) and emits bidClick with method: 'creativeClick'. It doesn’t change navigation or add overlays. Clicks inside nested cross-origin iframes, adUrl creatives, and clicks that navigate with JavaScript can’t be observed.
  • Native: clicks reported by the native creative (links with the pb-click class) emit bidClick with method: 'nativeClick' and the clicked assetId, if any. GAM clicks still come from the native template’s %%CLICK_URL_UNESC%% links, so enabling this doesn’t change what bidders or GAM receive. Native landing URLs are never fired as trackers.
  • Desktop fallback: with desktopFallback: true and the module included, on devices with a fine pointer, focus moving from the page into a creative’s iframe (not with the Tab key) is treated as a click and emits bidClickInferred. It’s a heuristic: some focus changes aren’t clicks, and some clicks don’t move focus.
  • Each bid emits at most one banner click event (observed or inferred), and with dedupeNativeClicks, one native click event.

Registering Clicks in GAM

Prebid line items using the dynamic creative already pass clickUrl: "%%CLICK_URL_UNESC%%". Enable fireTrackers to have Prebid request it on each observed click.

  • Prebid only requests resolved HTTPS URLs, and doesn’t request the click URL when the bid’s markup contains ${CLICKTHROUGH}, since that creative already sends its clicks through the ad server.
  • Requesting GAM’s click URL as a background request, rather than navigating through it, hasn’t been validated for GAM click counting or invalid-click treatment. Check the reported clicks against your expectations before relying on them.
  • Click tracking inside the bidder’s creative is independent, so clicks may also be counted elsewhere.

Why Click Counts Differ

Treat these events as an approximate, directional signal. Expect gaps against other sources in both directions:

  • Missed clicks: clicks Prebid can’t observe aren’t reported, such as those in nested cross-origin iframes, adUrl creatives, links that navigate with JavaScript, and Prebid Universal Creative line items. A click that unloads the page can be lost before an analytics adapter sends it.
  • Deduplication: banner events are limited to one per bid, and native events by default, while other trackers may count every click.
  • Inferred clicks: bidClickInferred is a heuristic. Some focus changes aren’t clicks, and some clicks don’t move focus.
  • Unverified reports: a frame on the page can report a click it didn’t receive (see Trust).
  • Different counting rules: the ad server, the bidder and other click trackers apply their own filtering, such as invalid-click detection, and count at different moments.

Trust

bidClick and bidClickInferred are signals, not verified clicks. Banner clicks are reported to Prebid by messages from the creative frame, and any frame on the page that knows the bid’s adId, including the creative’s own scripts, can send one without a click.

  • Prebid ignores these reports until the user has interacted with the page (navigator.userActivation.hasBeenActive), so no click can be reported for an impression nobody interacted with.
  • Ad server click URLs are only requested when the browser supports that check. Browsers without navigator.userActivation still get the event.
  • Once the user has interacted with the page, a frame can still report a click it didn’t receive, at most once per bid.

Analytics

Analytics adapters receive bidClick and bidClickInferred like other events. The event argument contains:

Field Description
bid The winning bid
adId, adUnitCode, bidder Identify the bid
method creativeClick, nativeClick, or iframeFocus (for bidClickInferred)
assetId The clicked native asset, if any

The generic analytics adapter’s skinny preset includes both events, with bid identifiers but without the bid, creative markup or click URL.

Further Reading