Trade Desk Universal Pixel, UID2, and Conversions API | OpsBlu Docs

Trade Desk Universal Pixel, UID2, and Conversions API

Technical guide to TTD Universal Pixel setup, conversion event tracking, Unified ID 2.0, first-party data segments, and Real-Time Conversions API.

How Trade Desk Tracking Works

The Trade Desk (TTD) tracking is built around the Universal Pixel, a JavaScript tag that loads from js.adsrvr.org and sends user activity to TTD's event processing infrastructure. The Universal Pixel serves three functions: site visitor tracking, conversion attribution, and audience segment qualification.

When the Universal Pixel fires:

  1. Sets a first-party cookie (TDID) containing the Trade Desk user identifier
  2. Initiates a cookie-sync chain with partner exchanges to map the TDID to exchange-specific IDs
  3. Checks for Unified ID 2.0 (UID2) tokens -- if present, associates the UID2 with the TDID for deterministic cross-device identity
  4. Sends the event payload (page URL, event type, custom data) to insight.adsrvr.org
  5. Evaluates the event against configured tracking tags (conversion definitions) and audience segment rules

The TDID serves as the probabilistic identifier, while UID2 provides deterministic identity resolution based on hashed email. When both are present, TTD's identity graph links them for cross-device attribution.

Data collected by the Universal Pixel feeds into TTD's Kokai AI engine, which uses conversion signals, audience composition, and real-time bidding data to optimize campaign performance across display, video, CTV, audio, native, and DOOH inventory.

Installing the Universal Pixel

The Universal Pixel consists of a base tag (loads once per page) and event-specific tracking tags (fire on conversions or segment-qualifying actions).

Base Tag

Place on every page, typically in the <head>:

<script src="https://js.adsrvr.org/up_loader.1.1.0.js" type="text/javascript"></script>
<script type="text/javascript">
ttd_dom_ready(function() {
    if (typeof TTDUniversalPixelApi === 'function') {
        var universalPixelApi = new TTDUniversalPixelApi();
        universalPixelApi.init("YOUR_ADVERTISER_ID", ["YOUR_UNIVERSAL_PIXEL_ID"], "https://insight.adsrvr.org/track/up");
    }
});
</script>

Replace:

  • YOUR_ADVERTISER_ID -- Your TTD advertiser ID (found in the TTD UI under Advertiser settings)
  • YOUR_UNIVERSAL_PIXEL_ID -- The pixel ID generated when creating a Universal Pixel in the TTD UI

The up_loader.1.1.0.js script handles cookie management, UID2 token detection, and event batching. It loads asynchronously and does not block page rendering.

Tag Manager Deployment (GTM)

Create a Custom HTML tag with the same snippet. Set the trigger to fire on All Pages. The base tag needs to fire before any conversion tracking tags.

Conversion Tracking

Conversions in TTD are defined as Tracking Tags within the Universal Pixel configuration. Each tracking tag has a unique tracking_tag_id and fires when specific conditions are met.

Static Conversion (URL-Based)

For conversions triggered by a specific page URL (e.g., /order-confirmation), configure the tracking tag in the TTD UI with a URL match rule. No additional code is needed beyond the base pixel.

Dynamic Conversion (Event-Based)

For conversions fired programmatically, add event tracking tags after the base pixel:

<script type="text/javascript">
ttd_dom_ready(function() {
    if (typeof TTDUniversalPixelApi === 'function') {
        var universalPixelApi = new TTDUniversalPixelApi();
        universalPixelApi.init("YOUR_ADVERTISER_ID", ["YOUR_UNIVERSAL_PIXEL_ID"], "https://insight.adsrvr.org/track/up",
        {
            "td1": "purchase",
            "td2": "ORDER-12345",
            "td3": "149.99",
            "td4": "USD"
        });
    }
});
</script>

Custom data fields:

  • td1 through td10 -- Free-form string fields for passing conversion metadata
  • These fields can be mapped to revenue, order ID, product category, etc. in the TTD reporting UI

Revenue and Order Tracking

TTD requires revenue data to be passed as a string in one of the td fields. In the TTD UI, you configure which td field maps to "Revenue" and which maps to "Order ID":

// Example: td2 = order ID, td3 = revenue, td4 = currency
universalPixelApi.init("ADV_ID", ["PIXEL_ID"], "https://insight.adsrvr.org/track/up", {
    "td1": "purchase",
    "td2": orderId.toString(),
    "td3": orderTotal.toFixed(2),
    "td4": "USD",
    "td5": productCount.toString()
});

First-Party Data Segments and UID2

Unified ID 2.0 (UID2)

UID2 is TTD's open-source identity framework that replaces third-party cookies with hashed, encrypted email-based identifiers. The flow:

  1. User provides email on your site (login, newsletter signup, checkout)
  2. Your server hashes the email and sends it to the UID2 Operator to generate a UID2 token
  3. The UID2 token is stored as a first-party cookie or passed to the Universal Pixel
  4. TTD uses the UID2 for deterministic cross-device matching and frequency management

Server-side UID2 token generation:

curl -X POST "https://prod.uidapi.com/v2/token/generate" \
  -H "Authorization: Bearer YOUR_UID2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email_hash": "SHA256_HASHED_EMAIL"
  }'

Response contains advertising_token (the UID2 to pass to the pixel) and refresh_token (for token rotation).

Client-side integration with the Universal Pixel:

// After obtaining the UID2 token from your server
ttd_dom_ready(function() {
    if (typeof TTDUniversalPixelApi === 'function') {
        var universalPixelApi = new TTDUniversalPixelApi();
        universalPixelApi.init("ADV_ID", ["PIXEL_ID"], "https://insight.adsrvr.org/track/up");
    }
});

// Set UID2 token (call after init, and on token refresh)
__ttduid2 = { advertising_token: "UID2_TOKEN_FROM_SERVER" };

First-Party Data Segments

Create targetable audience segments from your own data:

  1. CRM Upload -- Upload hashed email lists via the TTD UI or API. TTD matches against UID2 tokens and TDID identity graph.
  2. Pixel-Based Segments -- Define segment rules in the TTD UI based on Universal Pixel events (e.g., "users who viewed product pages in the last 7 days").
  3. Conversion-Based Segments -- Automatically segment users who completed specific conversions (purchasers, leads, etc.).

Data Marketplace

TTD's data marketplace provides third-party audience segments from providers including Oracle Data Cloud, Experian, Dun & Bradstreet, and Bombora (B2B intent). Segments are activated directly in campaign targeting without requiring pixel integration.

Real-Time Conversions API

The Real-Time Conversions API enables server-side conversion tracking, bypassing client-side pixel limitations.

Sending a Conversion

curl -X POST "https://insight.adsrvr.org/track/realtimeconversion" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "tracker_id": "YOUR_TRACKING_TAG_ID",
        "adv": "YOUR_ADVERTISER_ID",
        "event_name": "purchase",
        "value": 149.99,
        "currency": "USD",
        "order_id": "ORD-12345",
        "items": [
          {
            "item_code": "SKU-001",
            "name": "Running Shoes",
            "qty": 1,
            "price": 149.99
          }
        ],
        "adid": "TDID_VALUE",
        "uid2": "UID2_TOKEN"
      }
    ]
  }'

Required fields:

  • tracker_id -- The tracking tag ID from the TTD UI
  • adv -- Advertiser ID

Identity resolution (at least one required):

  • adid -- The TDID cookie value (first-party cookie)
  • uid2 -- A valid UID2 advertising token
  • ip + ua -- IP address and user agent (probabilistic matching, lower accuracy)

Batch Conversion Upload

For offline or delayed conversions, use the batch endpoint:

curl -X POST "https://insight.adsrvr.org/track/realtimeconversion" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {
        "tracker_id": "TAG_ID",
        "adv": "ADV_ID",
        "event_name": "offline_purchase",
        "value": 500.00,
        "order_id": "STORE-001",
        "timestamp": "2026-03-01T14:30:00Z",
        "uid2": "UID2_TOKEN_1"
      },
      {
        "tracker_id": "TAG_ID",
        "adv": "ADV_ID",
        "event_name": "offline_purchase",
        "value": 250.00,
        "order_id": "STORE-002",
        "timestamp": "2026-03-02T10:15:00Z",
        "uid2": "UID2_TOKEN_2"
      }
    ]
  }'

The API accepts up to 1,000 events per request. Events older than 30 days are not eligible for attribution.

Common Issues

The TDID cookie is set under the site's own domain (first-party). Common failure causes:

  • HTTP-only pages -- The pixel requires HTTPS. On HTTP pages, the cookie is not set.
  • Cookie consent blocking -- If a consent management platform blocks js.adsrvr.org before user consent, the pixel never loads. Ensure the pixel fires after consent is granted.
  • SameSite cookie policy -- The TDID cookie is set with SameSite=Lax. In cross-site iframe contexts, the cookie may not be accessible.

Verify with:

// Check for TDID cookie
console.log("TDID:", document.cookie.match(/TDID=([^;]+)/)?.[1] || "NOT SET");

Conversion Revenue Not Appearing in Reports

Revenue data must be passed as a string in one of the td fields, and that field must be mapped to the "Revenue" metric in the tracking tag configuration. Common mistakes:

  • Passing revenue as a number instead of a string (td3: 149.99 vs td3: "149.99")
  • Not configuring the field mapping in the TTD UI (Tracking Tag > Advanced Settings > Custom Data Mapping)
  • Currency mismatch between the pixel and the advertiser account settings

UID2 Token Expiration

UID2 tokens expire after approximately 6 hours. The refresh_token must be used to generate a new advertising_token before expiration. If the token expires, the pixel falls back to TDID-only identity resolution (probabilistic). Implement server-side token refresh:

curl -X POST "https://prod.uidapi.com/v2/token/refresh" \
  -H "Authorization: Bearer YOUR_UID2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "STORED_REFRESH_TOKEN"
  }'

Cross-Device Attribution Gaps

Without UID2, TTD relies on probabilistic matching via TDID cookie syncs with exchanges. This fails when:

  • Users browse in private/incognito mode (no persistent cookies)
  • Safari ITP purges cookies after 7 days of no interaction
  • Users switch between home and work networks (IP-based matching fails)

UID2 integration is the primary solution for deterministic cross-device tracking.

Real-Time Conversions API 400 Errors

Common causes of rejected API requests:

  • Missing tracker_id or adv field
  • Invalid uid2 token (expired or malformed)
  • order_id exceeds 128 character limit
  • Timestamp more than 30 days in the past

Platform-Specific Considerations

Kokai AI Engine -- TTD's Kokai platform powers automated bid optimization, budget allocation, and audience expansion. Kokai ingests Universal Pixel conversion data to build predictive models per advertiser. Campaigns with fewer than 50 conversions per week may not have sufficient signal for Kokai optimization; in those cases, manual bidding strategies may perform better.

CTV and Audio Tracking -- Connected TV and audio channels do not support JavaScript pixels or cookies. Attribution for CTV uses IP-based household matching: TTD logs the household IP at ad impression time, then matches it against site visits from the same IP within the attribution window. Audio attribution works similarly via device ID matching. Conversion data for these channels relies heavily on the Real-Time Conversions API with UID2 or IP+UA matching.

DOOH (Digital Out of Home) -- TTD supports DOOH inventory via SSP partners. Attribution uses mobile location data: TTD identifies mobile devices that were in proximity to a DOOH ad placement, then matches those device IDs against site visit or conversion data. This requires the user's mobile device to have been served a TTD ad previously (for device ID association).

Data Marketplace and Kokai Predictive Audiences -- Beyond standard third-party segments, TTD's data marketplace includes Kokai-generated predictive audiences. These are algorithmically built segments that identify users likely to convert based on cross-advertiser behavioral patterns. They are activated like any other data segment but are dynamically refreshed.

Frequency Management -- TTD frequency caps operate across all channels within an advertiser account. With UID2, frequency caps work cross-device (a user sees the cap regardless of device). Without UID2, frequency caps are per-cookie/device, which can lead to over-exposure across devices.

Reporting and Attribution Windows -- TTD defaults to 14-day click / 14-day view attribution. This can be configured per tracking tag from 1-90 days for clicks and 1-30 days for views. The attribution model uses last-touch by default, with options for even-credit and time-decay models available in custom reporting.

Nach oben