Match tag

The match tag is a small piece of code provided by The Trade Desk that you place on a website or within ads to enable cookie mapping (also known as cookie syncing). It associates The Trade Desk ID (TDID) with a partner's unique user ID for a browser or device, enabling both systems to recognize and measure activity across platforms.

TIP: If you need real-time data processing for cookie mapping, see Real-time ID tag.

Here's what you need to know:

• To get started and have your account provisioned with the proper permissions, you must complete the setup steps.
• To initiate cookie mapping, you must place The Trade Desk match tag on your website.
• The Trade Desk platform does not redirect all received cookie mapping requests. If a user cookie is determined as not persistent, no requests are returned. For details, see Redirecting URLs and Handling non-persistent TDIDs.
• If a mapping request is for a user covered by the General Data Protection Regulation (GDPR) but does not include a consent string, no cookie is written for the user. For details, see Data privacy.
• You must store and send back TDIDs that The Trade Desk platform sends to you.

The following sections describe the workflow for implementing the match tag.

Workflow overview

The cookie mapping workflow consists of the following steps:

1. Setup
2. Initiation
3. Redirecting URLs
4. Storing and sending back TDIDs
5. Handling non-persistent TDIDs

Setup

Before you get started, be sure to contact your Technical Account Manager to have your account provisioned with the proper permissions.

Information you need to provide

Provide your Technical Account Manager with the following information.

IMPORTANT: Use the match tag responses in the Redirecting URLs section as examples and be sure to include the macro codes listed for each parameter that you want to include in your redirect URL.

Information you need to receive

After the cookie-mapping pixel redirect URLs that you provide are set up as described in the Redirecting URLs section, the following information will be generated and provided to you by your Technical Account Manager.

Call the match tag

Place The Trade Desk match tag on your website in accessible web properties, where it can be called to initiate cookie mapping.

The following match tag example shows how to initiate cookie mapping using a ttd_pid and ttd_puid value.

<img height="1" width="1" style="border-style:none;" alt="" src="https://match.adsrvr.org/track/cmf/generic?ttd_pid={COOKIE_PARTNER_ID_PLACEHOLDER}&ttd_puid={OPTIONAL_ID_PLACEHOLDER}&ttd_tpi=1&gdpr=0"/>

The match tag supports the following parameters in the src attribute.

Pass-through parameter

To send data that is specific to your implementation, use the ttd_passthrough parameter. The Trade Desk passes these values without processing or changing the data.

Here are the key points about the pass-through parameter:

• The value for the ttd_passthrough parameter can include multiple name (value) pairs.
• You must encode the following characters if you use them as separators:
  • %3D for the equals sign (=) used as the separator in the name/value pair.
  • %26 for the ampersand (&) used before a subsequent parameter if there are multiple pass-through parameters.
• You must encode any other characters that are not URL-safe. For example, encode any spaces with the plus sign (+) or %20.

The following example shows the pattern for pass-through parameter values before encoding.

ttd_passthrough={PARAM1_NAME}={PARAM1_VALUE}&{PARAM2_NAME}={PARAM2_VALUE}&{PARAM3_NAME}={PARAM3_VALUE}

After applying the necessary URL encoding, the pattern is as follows:

ttd_passthrough={PARAM1_NAME}%3D{PARAM1_VALUE}%26{PARAM2_NAME}%3D{PARAM2_VALUE}%26{PARAM3_NAME}%3D{PARAM3_VALUE}

The following example passes through one parameter with parameter name example_creative and value 602206:

ttd_passthrough=example_creative%3D602206

The unencoded representation of this pass-through parameter is as follows:

example_creative=602206

The following example passes through two parameters and their values, with associated encoding:

ttd_passthrough=example_creative%3D602206%26example_videoid%3D1234B5678901FA

The unencoded representation of these two parameters, passed as the value of the ttd_passthrough parameter, is as follows:

example_creative=602206&example_videoid=1234B5678901FA

You can send more than two pass-through parameters, following the same pattern.

Domain parameter

If you're providing the domain parameter (see Call the match tag), the value must match the following rules.

Include only the following:

• Top-level domain extension (for example, .com, .co.uk)
• Domain
• (Optional) Sub-domain

Do not include the following:

• protocol (scheme), such as http or https
• Page name
• Path
• Query parameters
• Fragments (#)

Valid examples:

• example.com
• subdomain.example.co.uk

Examples of invalid values for the domain parameter:

• http://www.example.com
• https://subdomain.example.com/index.html
• https://example.com/products/item.html#item3

If you're populating the domain parameter using JavaScript, you might be able to use the window.location.hostname property. However, if the JavaScript is running in an iframe, window.location.hostname returns the domain of the iframe. In this scenario, you would need to add some logic to retrieve the hostname of the parent window.

Request examples

The following table shows examples of cookie mapping requests for various user types.

Redirecting URLs

The Trade Desk tag records incoming requests to capture the platform unique ID and issues a 302 redirect to the cookie-mapping pixel URL that you provided during setup.

The platform can pass back to you the following parameters: ttd_id, ttd_puid, gdpr, and gdpr_consent.

NOTE: The platform does not redirect all received cookie mapping requests. If a user cookie is determined as not persistent, no requests are returned.

Here's the decision process:

1. The Trade Desk checks to see if the user has an existing cookie with us:
   • If so, the platform reads the user's cookie and return the ID to you along with any ttd_puid that you might have sent.
   • If the user does not have an existing cookie with us, the platform writes a new cookie on that user's browser.
2. The Trade Desk makes an internal hop to read that user's new cookie:
   • If the platform can read the cookie, it returns the ID to you along with any ttd_puid that you may have sent.
   • If the platform cannot read the cookie, it drops the request and does not return an ID.
     This happens in around 10-15% of cookie mapping requests. It generally happens when a user has blocked third-party cookies set as their default or has a cookie-blocking extension installed in their browser. If the user is blocking third-party cookies, the platform doesn't want to store or transmit cookies that are not targetable, since they do not exist beyond one page load.

For example, if you have the following redirect URL:

https://example.com/sync?ttd_puid=%%PARTNER_UID%%&ttd_id=%%TDID%%&gdpr=%%GDPR_APPLIES%%&gdpr_consent=%%GDPR_CONSENT_STRING%%

The platform will respond back with the following:

https://example.com/sync?ttd_puid=123,456&ttd_id=1a2b3c4d-5e6f-7g8h-9i10-j11k12l13m14&gdpr=1&gdpr_consent=BOEFBi5OEFBi5AHABDENAI4AAAB9vABAASA

Here are other examples of redirect URLs:

https://map.example.com/partner/12345/sync?uid=%%TDID%%&_origin=1&gdpr=%%GDPR_APPLIES%%&gdpr_consent=%%GDPR_CONSENT_STRING%%&piggybackCookie=%%TDID%%

https://map.example.com/sync/v1?source_id=hash123&source_user_id=%%TDID%%&gdpr=%%GDPR_APPLIES%%&gdpr_consent=%%GDPR_CONSENT_STRING%%

Storing and sending back TDIDs

You must store TDIDs that The Trade Desk platform sends to you. You then send them back to us when you create segments by using the first-party POST /data/advertiser or third-party POST /data/thirdparty endpoints.

Handling non-persistent TDIDs

TDIDs derived from web browsers such as Safari and Firefox, which block third-party cookies by default, become non-persistent. This means that these TDIDs may never be seen again during bidding time.

From the targeting perspective, you have the following options for handling non-persistent TDIDs.

From a measurement perspective, the non-persistent TDIDs are likely to produce low-match rates so it is best to exclude them from upstream events.

TIP: You can find user agent and additional metadata within the headers from the redirect URLs of the match tag.

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.

https://match.adsrvr.org/track/cmf/generic?ttd_pid=cookiepartnerid&ttd_tpi=1&gdpr=1&gdpr_consent=BOEFBi5OEFBi5AHABDENAI4AAAB9vABAASA

If the consent string is not included when gdpr=1 is passed, the platform 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/cmf/generic?ttd_pid=cookiepartnerid&ttd_tpi=1&gdpr=0

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