@adcp/sdk API Reference - v14.0.0-beta.6
    Preparing search index...

    Type Alias PixelTrackerAsset

    PixelTrackerAsset: {} & {
        asset_type: "pixel_tracker";
        event:
            | "impression"
            | "viewable_mrc_50"
            | "viewable_mrc_100"
            | "viewable_video_50"
            | "audible_video_complete"
            | "click"
            | "custom";
        method?: "img"
        | "js";
        url: string;
        custom_event_name?: string;
        provenance?: Provenance;
    }

    A single renderer-fired HTTP tracker URL — image pixel or JavaScript include — bound to a measurement event (impression, viewability, click, custom). Generic web-pixel tracker primitive applicable to any web-rendered canonical format (image, html5, image_carousel, responsive_creative, sponsored_placement, native_*, plus the non-VAST/DAAST events of video_hosted and audio_hosted). The buyer's measurement vendor declares the tracker URL; the seller's renderer fires it at serve time without buyer-side involvement.

    The discriminated-union shape and event/method enums are formalized in IAB OpenRTB Native 1.2 (imptrackers[] / jstracker / eventtrackers[] / link.clicktrackers[]); the same shape applies cleanly to image banners, html5, carousels, and any other format whose renderer fires HTTP pixels for measurement. The name pixel_tracker mirrors the industry's existing 'tracker pixel' terminology (already used in url_type: "tracker_pixel") and applies equally to method: img and method: js (a JS include is still a measurement-pixel hop in vendor parlance).

    Scope boundary (normative). pixel_tracker covers RENDERER-FIRED trackers — measurement events that the ad's serving template invokes when the user sees, views, or clicks the creative. Conversion pixels that fire on the advertiser's site after the click (Meta Pixel, GA4 server-side, custom postbacks) MUST be modeled via sync_event_sources / event_log — they are campaign-scoped, not creative-asset-scoped. See docs/creative/canonical-formats.mdx#what-format_kind-is-not-for.

    Format-specific tracker primitives. Formats whose wire shape embeds tracker URLs in a format-specific structure use dedicated asset types instead:

    • video_vast → vast_tracker (VAST <TrackingEvents>: start, quartiles, complete, pause, mute)
    • audio_daast → daast_tracker (DAAST <TrackingEvents> parity)
    • display_tag → opaque (third-party server fires its own trackers)

    All other web-rendered canonicals use pixel_tracker.

    Maps to IAB OpenRTB Native 1.2 / Dynamic Native Ads API tracker objects:

    • imptrackers[] → one pixel_tracker per entry with event: impression, method: img
    • jstracker → one pixel_tracker with event: impression, method: js
    • eventtrackers[] → one pixel_tracker per entry, event mapped from the IAB event enum
    • link.clicktrackers[] → one pixel_tracker per entry with event: click, method: img (click destinations live on landing_page_url slot)

    Bidirectional v1↔v2 mapping (normative for SDK auto-negotiation). A 3.1 buyer SDK talking to a 3.0.x seller MUST downgrade pixel_tracker to the v1 {asset_type: url, url_type: tracker_pixel} shape. The URL still emits on the wire; what's lost depends on the original event/method. A 3.1 SDK reading a v1 manifest MUST upgrade {asset_type: url, url_type: tracker_pixel} to pixel_tracker by inferring event/method from the v1 asset_id. Both directions are lossy-with-advisory; SDKs MUST emit the appropriate error code so consumers can see what was inferred or dropped.

    v2 → v1 downgrade table:

    pixel_tracker source v1 emit Lost fields Error code
    {event: impression, method: img, url} {url_type: tracker_pixel, asset_id: impression_tracker, url} none (no advisory)
    {event: viewable_mrc_50, method: img, url} {url_type: tracker_pixel, asset_id: viewability_tracker, url} event variant PIXEL_TRACKER_LOSSY_DOWNGRADE
    {event: viewable_mrc_100, method: img, url} same shape event variant PIXEL_TRACKER_LOSSY_DOWNGRADE
    {event: viewable_video_50, method: img, url} same shape event variant PIXEL_TRACKER_LOSSY_DOWNGRADE
    {event: audible_video_complete, method: img, url} same shape event variant PIXEL_TRACKER_LOSSY_DOWNGRADE
    {event: click, method: img, url} {url_type: tracker_pixel, asset_id: click_tracker, url} none meaningful (no advisory)
    {event: custom, custom_event_name: X, ...} {url_type: tracker_pixel, asset_id: impression_tracker, url} (defaults to impression timing) custom event timing PIXEL_TRACKER_LOSSY_DOWNGRADE
    {method: js, any event, url} same shape with url_type: tracker_pixel JS execution context — URL is hit via GET (counter increments), but JS body doesn't execute (OMID-style verification, viewability observers, cross-domain cookie setters won't fire) PIXEL_TRACKER_LOSSY_DOWNGRADE

    v1 → v2 upgrade table (inferred — SDK has no explicit event/method):

    v1 source (asset_id) Inferred pixel_tracker Inference basis
    impression_tracker {event: impression, method: img} asset_id convention
    viewability_tracker {event: viewable_mrc_50, method: img} asset_id convention + most-common default (50% is the dominant variant in v1 catalogs)
    click_tracker {event: click, method: img} asset_id convention
    <other asset_id> {event: custom, custom_event_name: <original asset_id>, method: img} fallback — preserves the original asset_id as the custom name

    All v1→v2 upgrades surface PIXEL_TRACKER_UPGRADE_INFERRED so consumers can see that event/method were inferred rather than explicitly declared.

    Type Declaration

      • asset_type: "pixel_tracker"

        Discriminator identifying this as a renderer-fired pixel tracker asset. See /schemas/creative/asset-types for the registry.

      • event:
            | "impression"
            | "viewable_mrc_50"
            | "viewable_mrc_100"
            | "viewable_video_50"
            | "audible_video_complete"
            | "click"
            | "custom"

        Which event this tracker fires on. Event enum mirrors IAB OpenRTB Native 1.2 event-tracker registry (event types 1, 2, 3, 4, 500); the events themselves are generic web-pixel measurement events that apply to any renderer:

        • impression (IAB type 1) — fires when the ad is served. Covers both imptrackers[] and jstracker from the IAB shape, distinguished by method.
        • viewable_mrc_50 (IAB type 2) — IAB MRC viewable, 50% pixels for ≥1 second.
        • viewable_mrc_100 (IAB type 3) — IAB MRC viewable, 100% pixels for ≥1 second.
        • viewable_video_50 (IAB type 4) — video-specific viewable, 50% pixels for ≥2 seconds with audio on. On video_hosted; ignored on image/html5.
        • audible_video_complete (IAB type 500) — video reached 100% completion with audio on. Distinct from viewable_video_50 (50% pixels + 2s threshold) — this is the full-completion audible-view event. Meaningful on non-VAST video formats (Meta Reels, YouTube Shorts, TikTok Spark) where audible-complete is a measured event but VAST <TrackingEvents> isn't the wire format; VAST formats use vast_tracker with vast_event: complete plus a separate audible tracker instead.
        • click — fires when the user clicks the creative (link.clicktrackers[]).
        • custom — adopter-defined event for anything not in the standardized enum. MUST also set custom_event_name. Reserved for IAB Native event types 555+ (exchange-specific) and any vendor-defined event not yet promoted to a first-class enum value.
      • Optionalmethod?: "img" | "js"

        How the tracker URL is invoked at serve time:

        • img — fired as an image pixel (HTTP GET with <img>-like semantics; no JS execution)
        • js — fired as a script include (renderer evaluates the URL's response as JavaScript)

        Matches IAB OpenRTB Native 1.2 method enum (1=img, 2=js). js MUST only be used by sellers whose renderer supports JavaScript trackers; sellers without JS-tracker support MUST reject method: js declarations at sync_creatives time with CREATIVE_REJECTED carrying the reason.

      • url: string

        Tracker URL fired when event occurs. May carry AdCP universal macros (e.g., {MEDIA_BUY_ID}, {CREATIVE_ID}, {CACHEBUSTER}); the seller's renderer URL-encodes substituted values at serve time. See docs/creative/universal-macros.mdx.

      • Optionalcustom_event_name?: string

        REQUIRED when event is custom; otherwise MUST be absent. Adopter-defined event name. Sellers without registered handling for a given custom_event_name MUST silently no-op (do not fire) rather than reject — custom events are forward-compatible probes.

      • Optionalprovenance?: Provenance

      Settings

      Member Visibility