User Synchronization

Note

In the AdTech industry, user synchronization can be named differently: “user mapping,” “user matching,” or “cookie syncing”, and the steps involved may be described differently depending on the platform.

User synchronization helps all parties identify individual users. Most advertisers run performance-based campaigns, DSPs may not bid—or bid lower—when a user ID is missing. Therefore, properly configuring this has an important impact on your monetization.

When does it apply?

Caution

For desktop and mobile web, user synchronization is required for effective monetization and must be performed before enabling live requests. It does not apply to mobile apps.

Platform	Required
Web	✅ (also for Mobile Web)
App	❌

Requirements

1. Initiate the user synchronization by creating an iframe and loading the Adagio user matching URL (see process User Sync URLs).
2. Provide a redirection URL for Adagio (see User ID Macro).
3. If user sync succeeds, ensure bid requests include User IDs from Adagio and/or any other bidders (see Passing the User IDs in the bid request).

Note

Only works with users who have enabled cookie storage.

User Sync URLs

The Supplier initiates user syncing by creating an iframe with one of the following URLs and appropriate parameters.

Adagio provides one URL per region. For legal reasons, Users IDs are not shared between regions, so the User Sync and the Auctions must happen in the same region.

Danger

Serious risk of underperformance: syncing your user on a different regional endpoint than the one used to submit your BidRequests will result in the user being considered as unknown and will affect monetisation.

Example: User syncing for a Canadian user’s device would be done via the Adagio AMER data center. All Auctions for this same user would be done via the Adagio AMER data center.

Region	URL	City	Data Center
AMER	https://u-las.4dex.io/ortb/usync.html	Las Vegas	GCP us-west4
EMEA	https://u-ams.4dex.io/ortb/usync.html	Amsterdam	GCP europe-west4
APAC	https://u-tyo.4dex.io/ortb/usync.html	Tokyo	GCP asia-northeast1

Parameters

Parameter	Required	Description
publisher_id	Required	Id of the Publisher, found under the Settings menu in the Adagio Manager.
r	Required	The publisher must provide a redirect URL that is URL-encoded and passed in the r parameter. Example (raw URL): https://yourendpoint.com/setuid?us_privacy=1YYN&uid=\{UID\} Encoded value (for r parameter): https%3A%2F%2Fyourendpoint.com%2Fsetuid%3Fus_privacy%3D1YYN%26uid%3D%7BUID%7D
domain	Highly Recommended	The website domain where the user sync is initiated. Example: my.domain.com
gdpr	Required if applicable	GDPR status
gdpr_consent	Required if applicable	GDPR Consent string
us_privacy	Required if applicable	US Privacy string
gpp	Required if applicable	GPP string
gpp_sid	Required if applicable	GPP section id(s) in force for the current transaction

Sample URL for EMEA including the different parameters set:

https://u-ams.4dex.io/ortb/usync.html?publisher_id=1000&domain=my.domain.com&gdpr=0&gdpr_consent=&us_privacy=1YYN&r=https%3A%2F%2Fyourendpoint.com%2Fsetuid%3Fus_privacy%3D1YYN%26uid%3D%7BUID%7D

User ID Macro

Include a User ID macro in the redirect URL so Adagio can replace it with the final User ID.

• The User ID macro is: {UID}

Sample URL with macro:

https://yourendpoint.com/setuid?gpdr=0&gdpr_consent=&us_privacy=1YYN&uid={UID}

Sample URL with macro replaced:

https://yourendpoint.com/setuid?gpdr=0&gdpr_consent=&us_privacy=1YYN&uid=QHJ1Ok0yOFZLTUg4LU0tQzBSUjoyMDA0M3xwdToyQTM1RTg2OS0wQTM5LTQ4QTItQUM0NS1DNjkzOThBOUQ0OEE6MjAwNDM=

Cookie Expiration

The cookie remains valid for 60 days. To keep the identifiers up to date, renew it before it expires. Adagio will disregard expired user IDs.

Passing the User IDs in the Bid Request

Adagio User ID

If user matching succeeds and the user id is not expired, the bid request must include the user ID in the User object’s buyeruid attribute.

Example:

{
  "user": {
    "buyeruid": "QHJ1Ok0yOFZLTUg"
  }
}

Other bidders’ User IDs (Highly Recommended)

Caution

Highly recommended: Cookie matching is done asynchronously and must be done incrementally to optimise devices’ resources. It’s therefore imperfect.

If you already have the User ID of bidders monetising through the Adagio Demand Library, then it is highly recommended adding them to your Bid Request under bidrequest.user.ext.eids or bidrequest.user.eids, depending on your OpenRTB version.

Example OpenRTB 2.5

{
  "user": {
    "ext": {
      "eids": [
        {
          "source": "openx.com",
          "uids": [
            {
              "id": "6f492e90-621e-45a3-8f71-bcc9721a4279",
              "atype": 1
            }
          ]
        }
      ]
    }
  }
}

Example OpenRTB 2.6

{
  "user": {
    "eids": [
      {
        "source": "sovrn.com",
        "uids": [
          {
            "id": "JnA0AQZHz9xvgEOfTaKumBWJ",
            "atype": 1
          }
        ]
      }
    ]
  }
}

Below you’ll find the source that must be set for each of Adagio’s Demand Library’s bidder:

Bidder	EID Source
Magnite / Rubicon	rubiconproject.com
Pubmatic	pubmatic.com
OpenX	openx.com or openx.net
Sovrn	sovrn.com
TripleLift	triplelift.com
Equativ / Smart	smartadserver.com
ImproveDigital	improvedigital.com
Freewheel	freewheel.com
OneTag	onetag.com
RTB House	rtbhouse.com
Aidem	aidem.com
Nexxen / Unruly	unrulymedia.com
33Across	33across.com
ConnectAd	connectad.io
E-Planning	e-planning.net
Illumin / AcuityAds	acuityads.com
Insticator	ingage.tech