What is UID2 Token?

Unified ID 2.0 (UID2) is an open-source identity framework created by The Trade Desk that provides a deterministic identifier for advertising without relying on third-party cookies. UID2 identifiers are built from a user's hashed email address or phone number. A UID2 token, also called an advertising token, is an encrypted, short-lived form of the identifier that can be refreshed over time. The UID2 Token sync generates these tokens server-side for destinations that only accept UID2 tokens, such as The Trade Desk Real-Time Conversions API.

Product Type: Advertising

Integration Type: ID Sync

Capabilities

• Generates a UID2 token (advertising_token) server-side from an email or phone number made available after an identify() call. Unhashed values are hashed before they are sent.
• Refreshes the token on page load, so visitors who return within 30 days keep a valid token without another identify().
• Adds the token to server-side events for attribution and audience matching in destinations that require UID2 tokens.
• Removes the token when a user opts out of UID2, or when analytics.reset() is called (for example, on logout).

Considerations

• Important Activation Details: This sync runs through MetaRouter's Enrichment Service, which must be enabled for your MetaRouter environment. Contact your MetaRouter representative for assistance.
• Use with The Trade Desk - Conversions: This sync can be used with MetaRouter's The Trade Desk - Conversions integration. Use this sync instead of the Unified ID 2.0 sync when your destination only accepts UID2 tokens rather than raw UID2 values.
• The sync reads traits made available after an identify() fires, in this priority order: hashedEmail, email, hashedPhone, phone. Only one identifier is sent per request, and unhashed values are hashed before they are sent.
• Calling analytics.reset() (for example, on logout) removes the stored token, so the next person on a shared browser does not carry the previous user's token.

Sync Details

• IDs:

  • advertising_token – The UID2 token generated from the user's hashed email or phone number, used by destinations that require UID2 tokens for attribution and audience matching.

• Description:

  • The sync generates the UID2 token by sending a hashed email or phone trait to the MetaRouter ingestor route /v1/ttd/uid2/token, which calls UID2's POST /v2/token/generate endpoint.
  • The token is stored in first-party storage until the refresh period ends (30 days today). The token itself expires based on UID2's identity_expires value, which is not configurable.
  • On each page load after the refresh window opens, the sync refreshes the token through /v1/ttd/uid2/token/refresh. If the refresh chain has ended, the next page load generates a new token from stored traits when they include an email or phone; otherwise, the sync waits for the next identify(). Every identify() call also requests a new token.
  • If a generate call fails or the user has opted out, page-load generate calls pause for 1 day. If a refresh call fails temporarily, page-load refresh calls pause for 1 hour.
  • The token is added to server-side event payloads only while it is unexpired. MetaRouter decrypts it when the event is received, so destinations read it at context.providers.unifiedId2Token.encrypted.data.body.advertising_token.

• Response Example:

  JSON

  {
    "body": {
      "advertising_token": "A4AAAA...",
      "refresh_token": "...",
      "identity_expires": 1735689600000,
      "refresh_from": 1735688700000,
      "refresh_expires": 1735776000000,
      "refresh_response_key": "..."
    },
    "status": "success"
  }

• Server-side Event Payload:
  Upon completion of all vendor's sync, the server-side events will incorporate all resolved identifiers as described above. The following object will be appended to the context.providers property within the event's JSON payload:

  JSON

  {
    "unifiedId2Token": {
      "encrypted": {
        "data": "string"
      }
    }
  }

• Cookie Name:

  • Cookie: _meta_unifiedId2Token_data, _meta_unifiedId2Token_data_failure, _meta_unifiedId2Token_refresh_failure
  • IndexedDB: [your storage prefix]_unifiedId2Token_data, [your storage prefix]_unifiedId2Token_data_failure, [your storage prefix]_unifiedId2Token_refresh_failure
  • For a general guide on ID Sync validation, see here.

Sync Setup Guide

1. Gather Credentials

• To enable this sync, you must obtain a UID2 API Key and Client Secret with the Generator role. These are separate from the credentials used by the Unified ID 2.0 sync. These credentials are generated through the UID2 onboarding process documented here: Unified ID 2.0 Auth
• Once obtained, securely store these values for use in the integration request.

2. Add a UID2 Token Sync in MetaRouter

• Submit Integration Request Ticket

  • Submit a request through our support portal to enable UID2 enrichment services and configure your UID2 Token API Key and Client Secret. MetaRouter will implement these credentials on your behalf in a secure configuration file.
  • Example ticket description:
    • Ticket Name: Enable UID2 Token Enrichment and Credential Implementation
    • Ticket Description: Please enable enrichment services for our UID2 Token integration and implement our UID2 API credentials with the Generator role (attached securely).

• Add the UID2 Token Sync

  • To gather the advertising_token, you must add a UID2 Token sync.
    1. From the Pipelines page, find the pipeline associated with the web property you'd like to add a sync to. Hover over the three dot dropdown and select "Build AJS File."
    2. In the Identity Syncs section, select the UID2 Token sync.
    3. Fill out the following fields:
       1. API Timeout (in milliseconds) – Maximum time the Sync Injector waits for a response from the vendor's API. Example: 300
       2. MetaRouter Ingestor URL – Base domain for your MetaRouter ingestor. Do not include https:// or anything after .com. Example: mr.example.com
    4. Scroll down and click the Save and Build File button.
    5. Deploy your AJS file to propagate changes to your web property.