User Sync

Types of user sync endpoints

This documentation will cover user syncs for demand and supply partners. There are three main scenarios:

• For buyers who want to store their user ID in our match table so we send it to them in bid requests, use /xuid.
• To retrieve a user's TripleLift user ID (TLUID) to store in your match table, use /getuid.
• To retrieve the TLUID and have TripleLift sync with our partners (improving a supplier's match rate), use /sync in an iframe

See the following diagram to find the TripleLift user sync endpoint that applies to your situation.

Demand Partners

The first type of sync that we perform is user sync with our demand partners. Buyers that want to sync their user IDs with TripleLift may use one of the following endpoints:

Samples

/xuid
https://eb2.3lift.com/xuid?mid=tl_value_sample123&xuid=my_external_user_id&dongle=tl_value_sample456&gdpr=1&gdpr_consent=AABBCCDD

/getuid
https://eb2.3lift.com/getuid?redir=http%3A%2F%2FEXAMPLE.com%2FtlUid%3D$UID%26abc%3D456&us_privacy=1YYY

Examples

There are two main things to consider when setting up user sync with a demand partner:

• who stores the mapping (Triplelift or partner)
• who initiates the syncing (Triplelift, partner, or both)

TripleLift initiates, TripleLift stores:

• Triplelift calls Partner's sync endpoint:
  https://{partner-sync-endpoint}?redir=http://eb2.3lift.com/xuid? mid=tl_value_sample123&xuid=my_external_user_id&dongle=tl_value_sample456&gdpr={gdpr}&gdpr_consent={TC_string}

• Partner redirects (HTTPS GET) back to TL sync endpoint while replacing the macro
  placeholder with the actual Partner user ID (https://eb2.3lift.com/xuid? mid=tl_value_sample123&xuid=partner_value_789&dongle=tl_value_sample456&gdpr={gdpr}&gdpr_consent={TC_string})

• Triplelift receives the HTTPS redirect, extracts Partner user ID and records the mapping

Supply Partners:

The second type of sync that we perform is user sync with our supply partners. In supply-side server-to-server integrations, TripleLift does not have access to the browser/client and relies on our supply partners to pass us our tluid via an oRTB user field, namely user.buyeruid. In order to do this, we ask that our supply partners host the match table. A large majority of our supply partners are integrated with us in this way.

Each of the following options are prefaced with eb2.3lift.com:

The above endpoints are what TripleLift uses to send our partners a cookie ID for a particular request. The partner can then write the ID to a hosted match table and send it in subsequent bid requests. If the user is not cookied these endpoints will first set a cookie and then redirect to our partner’s user sync URL, interpolating the $UID macro with our cookie id in the process.

User Sync Set Up

The Partner Solutions Engineering team at TripleLift will follow these steps to set up a user sync for a supply partner:

• The publisher provides TripleLift the URL that they'll be using in the "redir" parameter, including the $UID macro.
• TripleLift adds the publisher's URL to our allowlist. Without this step, the sync will result in a 400 error with an X-Error header of "Unallowed sync domain". Reach out to your Solutions Engineer for the allowlisting process
• Ensure that the following user sync pixel works as a quick check before deploying to production pages:
  https://eb2.3lift.com/getuid?redir={publisher_encoded_redirect_url.com?uid=$UID}&gdpr=0
• If all steps above are accomplished, the publisher can proceed with dropping the pixel
  on all of their properties, ensuring the proper privacy parameters (GPP / GDPR) are present.

User Sync Flow

The following is the ideal flow in a publisher's live environment:

• Partner invokes /getuid or /sync endpoint with partner’s URL-encoded user sync URL in the
  redirect param:
  https://eb2.3lift.com/getuid?redir=https%3A%2F%2FEXAMPLE.com%3FtlUid%3D%24UID%26abc%3D456
• Triplelift sets a cookie, interpolates the $UID macro, and redirects back to the partner:
  https://EXAMPLE.com?tlUid=7584123529170110311&abc=456
• Partner sets their own cookie and writes both IDs to their hosted match table

Privacy Parameters:

Prerequisites
A publisher needs to have an IAB-compliant CMP operating on the page that properly sets the user’s consent if applicable.

GDPR Parameters
The following IAB documentation can provide further information on IAB Europe's TCF framework:
TCF 2.0 Documentation

If GDPR applies, the partner is responsible for appending the following parameters to our user sync endpoint:

• gdpr: The partner is responsible for appending gdpr=1 if the user is located in a GDPR
  territory
• gdpr_consent or cmp_cs: The partner is also responsible for appending the encoded users'
  consent string to our user sync endpoint: gdpr_consent={valid_consent_string}
  If GDPR applies and a valid consent string is NOT provided, TripleLift will not perform a sync. Additionally, if TripleLift detects the IP of the request is from a GDPR territory and none of the GDPR parameters are present, TripleLift will not perform a sync.

Note: 'gdpr' and 'gdpr_consent' / 'cmp_cs' are NOT required fields but without them TripleLift may not complete the sync as noted above.

CCPA Parameters
If CCPA applies, the partner is responsible for appending a us_privacy parameter to the user sync request URL containing a valid US Privacy string.

The following IAB documentation is available for more information on the US Privacy string: US Privacy Documentation

GPP Parameters

TripleLift sync endpoints accept two URL parameters as part of IAB's Global Privacy Platform:

• gpp: This contains the encoded GPP string.
• gpp_sid: Contains the section IDs of the applicable sections.

These can be used to communicate US National string information from the publisher's Consent Management Platform (CMP).