Real-time ID tag

The JavaScript real-time ID tag enables websites to copy a user's third-party The Trade Desk ID (TDID) cookie into a first-party cookie for server-side tracking. You can then use that first-party cookie in requests to the Real-Time Conversion Events API.

Here's what you need to know about the real-time ID tag:

• If you use real-time conversions, this is the best option for cookie mapping because it uses real-time data processing for targeting and measurement, and requires less infrastructure than the match tag solution.
• If your site serves users covered by GDPR, you'll need to modify the tag. It doesn't send consent parameters by default. For details, see Data privacy.

The following workflow sequence describes how the real-time ID tag works, from executing a tag on a website to creating a cookie mapping between the website and The Trade Desk:

1. The tag sends an API request from the browser to The Trade Desk's real-time ID service on the adsrvr.org domain.
2. The service reads and returns the TDID cookie in a JSON response.
3. The script writes the TDID cookie value to a first-party cookie.

This guide covers everything you need to set up, configure, troubleshoot, and maintain the real-time ID tag. See the following sections for details.

Setup

To install the realtime_id_tag.js tag, complete the following steps.

For details, see the following sections.

1. Obtain and enter a cookie partner ID

To sync the first-party cookie between the website and the advertiser using the real-time ID tag, you need to assign a unique cookie partner ID to your organization. To obtain and use this ID, do the following:

1. Contact your Account Manager or Technical Account Manager to obtain a cookie partner ID.
2. In the COOKIE_PARTNER_ID field of the TTD_RID_CFG configuration object, enter the ID.

2. Review the configuration

You can use the tag right away with its default values for the following items. Before you deploy the tag, be sure to review them and confirm they fit the needs of your site.

3. Add the JavaScript tag

Add the realtime_id_tag.js tag to the JavaScript code on the website using the method that best suits your needs.

For example, if you are adding the tag to Google Tag Manager (GTM) as a custom HTML tag, enclose the JavaScript code in HTML <script> tags and set the cookie partner ID, as shown in the following code sample.

IMPORTANT: To ensure the tag functions correctly, review the mandatory configuration items.

<script type="text/javascript">
/****************************************************************************
 * The Trade Desk REALTIME ID UTILITY
 * 
 * Example of using The Trade Desk real-time ID service to request a user's TDID cookie from adsrvr.org and write it as a first-party cookie.
 * Please review mandatory configuration items.
 ************************************************************************** */

/****************************************************************************
 *  CONFIGURATION ITEMS - PLEASE REVIEW
 ************************************************************************** */
var TTD_RID_CFG = {
  /***
   *  MANDATORY TO REVIEW
   * */
  COOKIE_PARTNER_ID: '<COOKIE_PARTNER_ID_PLACEHOLDER>',  //Cookie partner ID issued by The Trade Desk.
  FIRSTPARTY_COOKIE: 'ttd_TDID',             //Name of the first-party cookie holding The Trade Desk TDID.
  FIRSTPARTY_COOKIE_OPTIONS: 'path=/;secure;SameSite=Strict;', //Options for setting the first-party cookie. Refer to standard JavaScript document.cookie. documentation.  
                                              //IMPORTANT: You may need to override the domain to make the cookie accessible on 
                                              //required subdomains. For example, for website www.example.com, add 'domain=.example.com;' for 
                                              //the cookie to be accessible on subdomain.example.com.

  /***
   *  DEFAULT SETTINGS
   * */
  LOG_TO_CONSOLE: false,                       //Whether to log debug messages. TIP: Set to false for production use or true for testing.
  LOG_MESSAGE_PREFIX: 'TTD_REALTIME_ID: ',    //Helpful prefix for finding debug messages in the browser console.
  FIRSTPARTY_COOKIE_WRITE: true,              //Whether to write the retrieved TDID as a first-party cookie. When disabled the 
                                              //TDID can still be loaded on every page and sent to registered callback functions.
  FIRSTPARTY_COOKIE_ALWAYS_REFRESH: false,    //whether to always refresh the cookie.
  FIRSTPARTY_COOKIE_EXPIRY_DAYS: 7,           //How long the first-party cookie will last. Lower numbers prompt more regular refreshes 
                                              //To keep in sync with the user's adsrvr.org TDID cookie (which may change). 
  RID_BASE_URL: 'https://match.adsrvr.org/track/rid?fmt=json',
  RID_INCL_DOMAIN: true,                      //Whether to pass the domain value to the real-time ID service, e.g. &domain=www.example.com).
  RID_DOMAIN_VALUE: window.location.hostname, //What value to send as the domain.
  RID_REQUEST_OPTIONS: {                      //Fetch() request options.
    credentials: 'include',                   //Provide existing cookies (Required!)
    mode: 'cors',                             //*cors, no-cors, same-origin
    cache: 'no-cache'                         // *default, reload, no-cache, force-cache, only-if-cached
  },
  CALLBACKS: []                               // List of callback functions to run after the real-time ID finishes. 
                                              //See the CUSTOM CALLBACKS section for examples of how to register callback functions.
                                              //Must accept two parameters: TTD_RID_STATUS code and tdid.
}


/****************************************************************************
 * CUSTOM CALLBACKS 
 * Customize to add callbacks to run after execution completes.
 * Callback functions must accept two parameters: 
 *  @status: The TTD_RID_STATUS code that the real-time ID tag finished with. (See the CONSTANTS section.) 
 *  @tdid: The tdid cookie value.
 ************************************************************************** */

/*
// Example of registering a callback function
TTD_RID_CFG.CALLBACKS.push(function(status, tdid) {
  ttd_log('Example callback executing (status='+status+', tdid='+tdid+')');
});
*/


/****************************************************************************
 *  'CONSTANTS'
 ************************************************************************** */

/***
 *  Status codes summarizing how the real-time ID lookup finished.
 * */
var TTD_RID_STATUS = {
  NEW: 'NEW',             //A new first-party cookie was written.
  REFRESHED: 'REFRESHED', //The first-party cookie was refreshed (it already existed).
  SKIPPED: 'SKIPPED',     //A first-party cookie already exists, and the refresh was skipped.
  FAILED: 'FAILED',       //A failure occurred.
  REJECTED: 'REJECTED'    //The real-time ID service rejected the request.
}


/****************************************************************************
 *  FUNCTIONS
 ************************************************************************** */

/****
 * Run any callbacks that have been registered.
 *  @status: The TTD_RID_STATUS code that the real-time ID tag finished with. 
 *  @tdid: The TDID value. Only provided for NEW, REFRESHED and SKIPPED statuses.
 * */
var ttd_executeCallbacks = function(status, tdid) {
  ttd_log('ttd_executeCallbacks('+status+', '+tdid+')');
  for(var i in TTD_RID_CFG.CALLBACKS) {
    if(typeof TTD_RID_CFG.CALLBACKS[i] === 'function') {
      TTD_RID_CFG.CALLBACKS[i](status, tdid);
    }
  }
}


/****
 * Proxy function for logging. It will log to the console if TTD_LOG_TO_CONSOLE is true, and will output messages with a configured prefix. Simple types will output inline. Objects, etc., will be a second log message.
 * */
var ttd_log = function(logMessage) {

  if(!TTD_RID_CFG.LOG_TO_CONSOLE) return;

  switch(typeof(logMessage)) {
    case 'string':
    case 'boolean':
    case 'number':
      console.log(TTD_RID_CFG.LOG_MESSAGE_PREFIX + logMessage);
      break;
    default:
      console.log(TTD_RID_CFG.LOG_MESSAGE_PREFIX + '..['+typeof(logMessage)+']..');
      console.log(logMessage);
  }  
}

/****
 * Get a timestamp string compatible with document.cookie expiration, X days from now.
 * @days: Number of days.
 * */
var ttd_getNowPlusDaysString = function(days)
{
  ttd_log('ttd_getNowPlusDaysString('+days+')');

  var millisecondsPerDay = 86400000;

  var now = new Date();
  var time = now.getTime();
  var expireTime = time + (millisecondsPerDay*days);
  now.setTime(expireTime);
  return now.toUTCString();
}

/****
 * Write a cookie to the first-party domain.
 * @cookie_name: Name of the cookie.
 * @value: Value of the cookie.
 * @expiryString: A pre-formatted expiration timestamp compatible with document.cookie.
 * @options: Additional options compatible with the document.cookie string. Example: "path=/;secure;SameSite=Strict;"
 * */
var ttd_writeCookie = function(cookie_name, value, expiryString, options) {
  ttd_log('ttd_writeCookie('+cookie_name+','+value+','+expiryString+')');
  var setCookieString = cookie_name+"="+value+";expires="+expiryString+";"+options;
  ttd_log('Setting Cookie as: '+setCookieString);
  document.cookie = setCookieString;
}


/****
 * Returns the value of a first-party cookie. Or returns false if the cookie cannot be found.
 * @cookie_name: Name of the cookie.
 * */
var ttd_getCookie = function(cookie_name) {

  ttd_log('ttd_getCookie('+cookie_name+')');

  cookie_name += "=";
  var allCookies = decodeURIComponent(document.cookie);

  var cookieArr = allCookies.split(';');
  for(var i = 0; i <cookieArr.length; i++) {
    var cookieString = cookieArr[i];

    while (cookieString.charAt(0) == ' ') {
      cookieString = cookieString.substring(1);
    }
    if (cookieString.indexOf(cookie_name) == 0) {
      return cookieString.substring(cookie_name.length, cookieString.length);
    }
  }
  return false;
}


/****
 * Get the request URL generated from relevant settings.
 * */
var ttd_getRequestUrl = function() {
  var requestUrl = TTD_RID_CFG.RID_BASE_URL + '&ttd_pid=' + TTD_RID_CFG.COOKIE_PARTNER_ID;

  if(TTD_RID_CFG.RID_INCL_DOMAIN) {
    return requestUrl + '&domain=' + TTD_RID_CFG.RID_DOMAIN_VALUE;
  }
  else {
    return requestUrl;
  }
}



/****************************************************************************
 *  EXECUTION
 ************************************************************************** */

var ttd_initRID = function() {

  var currentFirstPartyCookieValue = ttd_getCookie(TTD_RID_CFG.FIRSTPARTY_COOKIE);

  if(TTD_RID_CFG.FIRSTPARTY_COOKIE_ALWAYS_REFRESH == true || currentFirstPartyCookieValue === false) {

    try {
      //Execute the request to the real-time ID service.
      fetch(ttd_getRequestUrl(), TTD_RID_CFG.RID_REQUEST_OPTIONS)
        .then(function(response) {
          ttd_log('Converting JSON response to object.');
          return response.json();
        })
        .then(function(data) {
          if(typeof(data.TDID) !== 'string') {
            ttd_log('RID did not return a TDID. Review Network request response.');
            ttd_executeCallbacks(TTD_RID_STATUS.REJECTED, false);
            return;
          }
          else {
            ttd_log('TDID is '+data.TDID);

            //Write the first-party cookie.
            if(TTD_RID_CFG.FIRSTPARTY_COOKIE_WRITE) {
              ttd_writeCookie(TTD_RID_CFG.FIRSTPARTY_COOKIE, 
                              data.TDID, 
                              ttd_getNowPlusDaysString(TTD_RID_CFG.FIRSTPARTY_COOKIE_EXPIRY_DAYS), 
                              TTD_RID_CFG.FIRSTPARTY_COOKIE_OPTIONS
                              );
            }

            //Determines if we are setting a new cookie or refreshing an existing cookie.
            if(currentFirstPartyCookieValue === false) {
              ttd_executeCallbacks(TTD_RID_STATUS.NEW, data.TDID);
            }
            else {
              ttd_executeCallbacks(TTD_RID_STATUS.REFRESHED, data.TDID);
            }
          }
        })
        .catch(function(error) {
          ttd_log('Caught error handling fetch response.');
          ttd_log(error);
          ttd_executeCallbacks(TTD_RID_STATUS.FAILED, false);
        });
    } catch (error) {
      ttd_log('Caught error during fetch request.');
      ttd_log(error)
      ttd_executeCallbacks(TTD_RID_STATUS.FAILED, false);
    }
  }
  else {
    ttd_log('Skipped cookie refresh.');
    ttd_executeCallbacks(TTD_RID_STATUS.SKIPPED, currentFirstPartyCookieValue);
  }

  return;
}(); // EXECUTE
</script>

This completes the steps for adding a real-time ID tag.

Advanced configuration

To configure how the realtime_id_tag.js tag interacts with the website and the Real-Time Conversion Events API, adjust the settings for requests, logging, and first-party cookies. These options allow you to control data sharing, debugging, and customization through callbacks.

Request options

To determine how the API service is used, configure the following settings.

First-party cookie options

To update first-party cookie details that the real-time ID tag writes to the browser, use the following options.

Debug logging

For testing and troubleshooting, turn on debug logging by using the following options.

Callback functions

TIP: When using a real-time ID tag with asynchronous or parallel tasks, consider possible race conditions. For example, tracked events (page views, add-to-cart actions, and purchases) might be sent to a server-side tracking solution before TDIDs are available, causing those events to lack TDIDs.

To reduce potential race conditions, the real-time ID tag provides callback functions that initiate follow-up actions and requests after completing its cookie mapping. To customize real-time ID tag behavior, use the following callback function.

GTM (simple)

When using the real-time ID tag with GTM, the TDID might become available only after events have been tracked and sent to The Trade Desk. For example, in a server-side GTM integration with The Trade Desk Real-Time Conversion Events API that sends page view events, if these events are sent to the server-side GTM before a TDID is stored as a first-party cookie, they might lack sufficient identity details for attribution in The Trade Desk campaigns.

As a solution, use the callback functionality of the tag to push an additional, delayed page view event to the GTM data layer after the TDID is obtained. This allows a page view event to be sent from the server-side GTM to The Trade Desk with the TDID included, if it was missing previously.

The following example shows how to add the callback function to the script.

TTD_RID_CFG.CALLBACKS.push(function(status, tdid) {
  ttd_log('CALLBACK EXAMPLE ('+status+', '+tdid+') - When a new first party cookie has been obtained. Send an event to GTM data layer. (basic example)');
  switch(status) {
    case TTD_RID_STATUS.NEW:
        ttd_log('Adding custom ttd_page_view event to GTM data layer.');
        window.dataLayer.push({'event':'ttd_page_view'});
      break;

    //Do nothing for other statuses.
    case TTD_RID_STATUS.REFRESHED:
    case TTD_RID_STATUS.SKIPPED:
    case TTD_RID_STATUS.FAILED:
    case TTD_RID_STATUS.REJECTED:
    default:
      //No action is needed.
      break;
  }
});

After adding the callback function, consider configuring the following options:

• The client-side GTM to send new ttd_page_view events to the server-side GTM.
• The server-side GTM to use events called ttd_page_view as an additional trigger for sending page view event data to The Trade Desk Real-Time Conversion Events API. This assumes normal page-view events are already being sent to the Real-Time Conversion Events API.

GTM (advanced)

To avoid inflated hit counts, use a more advanced version of Push page view event to GTM (simple) that sends the delayed page view event only when necessary. This version attempts to send an additional page view event only if a regular page view event has already occurred. It also avoids sending duplicate events to the data layer, even if the real-time ID tag executes multiple times.

The following example shows how to add the advanced callback function to the script.

TTD_RID_CFG.CALLBACKS.push(function(status, tdid) {
  ttd_log('CALLBACK EXAMPLE ('+status+', '+tdid+') - When a new first party cookie has been obtained. Send an event to GTM data layer. (advanced example)');
  switch(status) {
    case TTD_RID_STATUS.NEW:
      
      //Assumption: The delayed page view and the "real" page view have different names.
      var pageViewEventName = 'gtm.js'; //gtm.js == "Container Loaded" == Page View
      var delayedPageViewEventName = 'ttd_page_view'; //Custom page view event name.
      var hasPageViewEventOccurred = false;
      var hasDelayedPageViewEventOccurred = false;

      //Look through existing data layer events. Assumes each item is an object with a key called "event" which holds the event name.
      for(var i in window.dataLayer) {
      
        if(typeof window.dataLayer[i] == 'object') {
          if(window.dataLayer[i].event == pageViewEventName) {
            hasPageViewEventOccurred = true;
            ttd_log('Found existing page view event ('+pageViewEventName+')');
          }
          if(window.dataLayer[i].event == delayedPageViewEventName) {
            hasDelayedPageViewEventOccurred = true;
            ttd_log('Found existing DELAYED page view event ('+delayedPageViewEventName+')');
          }
        }
      }

      //If the "regular" page view event already occurred, it was before the first-party cookie was set. 
      // Also check in case the delayed page view event was already submitted.
      if(hasPageViewEventOccurred === true && hasDelayedPageViewEventOccurred === false) {
        ttd_log('Inserting delayed page view event to datalayer ('+delayedPageViewEventName+')');
        window.dataLayer.push({'event':delayedPageViewEventName});
      }
      
      break;

    //Do nothing for other statuses.
    case TTD_RID_STATUS.REFRESHED:
    case TTD_RID_STATUS.SKIPPED:
    case TTD_RID_STATUS.FAILED:
    case TTD_RID_STATUS.REJECTED:
    default:
      //No action is needed.
      break;
  }
});

Send the TDID to the Real-Time Conversion Events API

After the real-time ID tag writes the TDID to the first-party cookie, read that cookie value whenever you call the Real-Time Conversion Events API. Pass it in the tdid field of the POST /track/realtimeconversion request so the platform can attribute the conversion to the correct user.

NOTE: This differs from the match tag workflow. You don't need to send the TDID back to The Trade Desk through the POST /data/advertiser or POST /data/thirdparty segment-creation endpoints. Those endpoints are used for building audiences, not for real-time conversion tracking. The real-time ID tag's cookie value is used directly as the tdid field on each conversion event.

Troubleshooting

If the realtime_id_tag.js tag doesn't seem to be working, for example, no first-party cookie is set, or the expected request to adsrvr.org doesn't fire, use the following checks in order to diagnose the issue.

NOTE: These checks use Chrome Developer Tools.

1. Check first-party cookie

To check if the first-party cookie was set, do the following.

1. In Chrome Developer Tools, go to Application.
2. In the left-side menu, select Cookies, then select the current domain.
3. Order the cookies by name. In some browsers, cookies starting with uppercase letters are ordered before the ones starting with lowercase.
4. Find the new first-party cookie set on the current domain, not adsrvr.org. By default, the cookie is called ttd_TDID.

If you find the cookie, the tag is working correctly and you can skip the rest of the sections. To re-check, delete the cookie. If not found, continue to the next check.

2. Verify JavaScript

To verify the JavaScript is on the website, in the browser console, enter TTD_RID_CFG. The details of the configuration object is returned. See the following table for next steps.

After you verify the JavaScript, continue to the next check.

3. Check request status

To check the status of the real-time ID tag request, do the following:

1. In the Network tab of the Chrome Developer Tools, look for requests to https://match.adsrvr.org/track/rid?. If requests are missing, something is likely failing in the JavaScript tag execution.

NOTE: If the first check confirmed that a first-party cookie has been set, the absence of a real-time ID tag network request is expected because, by default, the request is made only when a first-party cookie has not been set.

1. In the console, check for the following:

• The response code is HTTP 200.
• In the Response tab, the JSON response body provides a TDID GUID value.

If both are correct, continue to step 3. Otherwise, skip to Add debug logging.

1. Check request parameters for the following:

• The ttd_pid value matches the cookie partner ID provided by The Trade Desk.
• The domain parameter is sending the current domain.

NOTE: If the website is in Europe, make sure the domain name has been provided to The Trade Desk for GDPR allow listing.

If you have the correct response for both, this check is complete. Continue to Add debug logging.

4. Add debug logging

If further information is needed for troubleshooting, update the tag to provide more debug-logging messages in the console:

1. In the JavaScript, update the LOG_TO_CONSOLE property for the real-time ID tag to true.
2. Re-publish the updated JavaScript.

Look for debug messages in the console. By default, these have the TTD Realtime ID: prefix.

Reference

To help with configuration and troubleshooting, the following sections provide additional technical information about the real-time ID tag.

API parameters

NOTE: To ensure compatibility with the GTM custom HTML tag type, the tag avoids using the more recent ECMAScript syntax.

The tag uses the JavaScript fetch() function to request the user's TDID cookie from The Trade Desk real-time ID tag API.

Here's an example endpoint URL that the fetch() call would use: https://match.adsrvr.org/track/rid?ttd_pid=partner1234&fmt=json&domain=www.example.com

The following table describes the request parameters.

Consent parameters

The following parameters are supported by the real-time ID tag API, but are not supported by the JavaScript tag. If the website uses the IAB TCF, you must modify the tag to collect and send this data to the real-time ID tag API service.

Response details

The response is provided in JSON format, which can be parsed into a JavaScript object. The JavaScript will write the TDID value to a first-party cookie. For details, see First-party cookie options.

NOTE: The API service might provide an empty response body, particularly when user consent requirements have not been met. The tag is designed to handle this exception gracefully without causing browser errors (unless logging is enabled).

The following table describes the response properties.

Data privacy

Data protection laws provide requirements for the use of cookies and pixel technology in European regions. Consent must be obtained from users before cookies can be used for advertising purposes, including cookie mapping, retargeting and reporting.

Request examples for GDPR-regulated users

If you have the user's consent to write a cookie to their browser, pass gdpr=1 and include the user's consent string in the gdpr_consent parameter. For details, see Consent parameters.

https://match.adsrvr.org/track/rid?ttd_pid=cookiepartnerid&fmt=json&domain=www.example.com&gdpr=1&gdpr_consent=BOEFBi5OEFBi5AHABDENAI4AAAB9vABAASA

If the consent string is not included when gdpr=1 is passed, we will not write a cookie for the user.

Request examples for non-GDPR regulated users

If the user is not regulated by GDPR, pass gdpr=0.

https://match.adsrvr.org/track/rid?ttd_pid=cookiepartnerid&fmt=json&domain=www.example.com&gdpr=0

For requests where gdpr=0 and the request passes validation, we will write a cookie and respond with the associated ttd_id.

FAQs

The following is a list of commonly asked questions about the real-time ID tag.

How do I use the real-time ID tag with Google Tag Manager?

Add realtime_id_tag.js as a GTM custom HTML tag. Wrap the script in <script> tags and set COOKIE_PARTNER_ID as described in Add the JavaScript tag.

Here's what you need to know about using the real-time ID tag as a GTM custom HTML tag:

• The simple version above can inflate hit counts if it fires every time the tag runs. See the advanced example [#example-gtm-advanced] if you need to check the data layer for an existing page view before pushing the delayed one.
• In a server-side GTM setup, page view events may be sent to the Real-Time Conversion Events API before the TDID cookie exists, which means those events can be missing identity details. To fix this, register a CALLBACKS function that pushes a delayed ttd_page_view event to the GTM data layer once the TDID is retrieved. For details on how callbacks work generally, see the FAQ on customizing tags.

TTD_RID_CFG.CALLBACKS.push(function(status, tdid) {
  switch(status) {
    case TTD_RID_STATUS.NEW:
      window.dataLayer.push({'event':'ttd_page_view'});
      break;
    default:
      break;
  }
});

Configure the client-side GTM to forward this ttd_page_view event to the server-side GTM, and configure the server-side GTM to use it as an additional trigger for the Real-Time Conversion Events API call.

How do I use the tag in the European region?

Data protection law in the EU requires user consent before cookies can be used for advertising, retargeting, or reporting. This impacts the real-time ID tag in two ways:

• Domain allow-listing: If your website is in Europe, your domain must be provided to The Trade Desk for GDPR allow-listing, or cookie mapping requests will fail.
• Consent parameters: The real-time ID service supports gdpr and gdpr_consent parameters, but the JavaScript tag does not send them by default. If your site uses the IAB TCF, you'll need to modify the tag to collect and pass these values yourself. See Consent parameters for parameter details.

For request-level examples of GDPR vs. non-GDPR handling, see Data privacy.

Can I customize the tag after I've added it to my site?

Yes. You can configure through the TTD_RID_CFG object; there's no need to touch the core script logic. The following table explains what you can configure.