> For the complete documentation index, see [llms.txt](https://adagio-io.gitbook.io/adagio-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adagio-io.gitbook.io/adagio-documentation/openrtb-s2s-endpoint/user-synchronization.md).

# User Synchronization

{% hint style="info" %}
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.
{% endhint %}

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?

{% hint style="warning" %}
**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.
{% endhint %}

<table><thead><tr><th width="187.17578125">Platform</th><th width="274.5">Required</th></tr></thead><tbody><tr><td>Web</td><td>✅ (also for Mobile Web)</td></tr><tr><td>App</td><td>❌</td></tr></tbody></table>

## Requirements

1. Initiate the user synchronization by creating an iframe and loading the Adagio user matching URL (see process [User Sync URLs](https://adagio-io.gitbook.io/adagio-documentation/openrtb-s2s-endpoint/user-synchronization#user-sync-urls)).
2. Provide a redirection URL for Adagio (see [User ID Macro](https://adagio-io.gitbook.io/adagio-documentation/openrtb-s2s-endpoint/user-synchronization#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](https://adagio-io.gitbook.io/adagio-documentation/openrtb-s2s-endpoint/user-synchronization#passing-the-user-ids-in-the-bid-request)).

{% hint style="info" %}
Only works with users who have enabled cookie storage.
{% endhint %}

## 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, <mark style="color:orange;">**Users IDs are not shared between regions, so the User Sync and the Auctions must happen in the same region.**</mark>

{% hint style="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.
{% endhint %}

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.

<table><thead><tr><th width="106">Region</th><th width="383.89453125">URL</th><th width="131">City</th><th width="263.015625">Data Center</th></tr></thead><tbody><tr><td>AMER</td><td><a href="https://u-las.4dex.io/ortb/usync.html"><code>https://u-las.4dex.io/ortb/usync.html</code></a></td><td>Las Vegas</td><td>GCP us-west4</td></tr><tr><td>EMEA</td><td><a href="https://u-ams.4dex.io/ortb/usync.html"><code>https://u-ams.4dex.io/ortb/usync.html</code></a></td><td>Amsterdam</td><td>GCP europe-west4</td></tr><tr><td>APAC</td><td><a href="https://u-tyo.4dex.io/ortb/usync.html"><code>https://u-tyo.4dex.io/ortb/usync.html</code></a></td><td>Tokyo</td><td>GCP asia-northeast1</td></tr></tbody></table>

### Parameters

<table><thead><tr><th width="188">Parameter</th><th width="200.2421875">Required</th><th width="634.3359375">Description</th></tr></thead><tbody><tr><td><code>publisher_id</code></td><td><mark style="color:red;">Required</mark></td><td>Id of the Publisher, found under the <em>Settings</em> menu in the <a href="https://app.adagio.io">Adagio Manager</a>.</td></tr><tr><td><code>r</code></td><td><mark style="color:red;">Required</mark></td><td><p>The publisher must provide a redirect URL that is URL-encoded and passed in the <code>r</code> parameter.</p><p><strong>Example (raw URL):</strong><br><code>https://yourendpoint.com/setuid?us_privacy=1YYN&#x26;uid={UID}</code></p><p><strong>Encoded value (for <code>r</code> parameter):</strong><br><code>https%3A%2F%2Fyourendpoint.com%2Fsetuid%3Fus_privacy%3D1YYN%26uid%3D%7BUID%7D</code></p></td></tr><tr><td><code>domain</code></td><td><mark style="color:orange;">Highly Recommended</mark></td><td>The website domain where the user sync is initiated. Example: <em>my.domain.com</em></td></tr><tr><td><code>gdpr</code></td><td><mark style="color:red;">Required</mark> if applicable</td><td>GDPR status</td></tr><tr><td><code>gdpr_consent</code></td><td><mark style="color:red;">Required</mark> if applicable</td><td>GDPR Consent string</td></tr><tr><td><code>us_privacy</code></td><td><mark style="color:red;">Required</mark> if applicable</td><td>US Privacy string</td></tr><tr><td><code>gpp</code></td><td><mark style="color:red;">Required</mark> if applicable</td><td>GPP string</td></tr><tr><td><code>gpp_sid</code></td><td><mark style="color:red;">Required</mark> if applicable</td><td>GPP section id(s) in force for the current transaction</td></tr></tbody></table>

*Sample URL for EMEA including the different parameters set:*

{% code overflow="wrap" %}

```url
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
```

{% endcode %}

## 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:*

{% code overflow="wrap" %}

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

{% endcode %}

*Sample URL with macro replaced:*

{% code overflow="wrap" %}

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

{% endcode %}

### Cookie Expiration

The cookie remains <mark style="color:orange;">valid for 60 days</mark>. 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:*

{% code overflow="wrap" %}

```json
{
  "user": {
    "buyeruid": "QHJ1Ok0yOFZLTUg"
  }
}
```

{% endcode %}

### Other bidders' User IDs (Highly Recommended)

{% hint style="warning" %}
**Highly recommended:** Cookie matching is done asynchronously and must be done incrementally to optimise devices' resources. It's therefore imperfect.
{% endhint %}

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.

{% tabs %}
{% tab title="Example OpenRTB 2.5" %}
{% code overflow="wrap" %}

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

{% endcode %}
{% endtab %}

{% tab title="Example OpenRTB 2.6" %}
{% code overflow="wrap" %}

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

{% endcode %}
{% endtab %}
{% endtabs %}

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

<table><thead><tr><th width="224.953125">Bidder</th><th width="302.9375">EID Source</th></tr></thead><tbody><tr><td>Magnite / Rubicon</td><td><code>rubiconproject.com</code></td></tr><tr><td>Pubmatic</td><td><code>pubmatic.com</code></td></tr><tr><td>OpenX</td><td><code>openx.com</code> or <code>openx.net</code></td></tr><tr><td>Sovrn</td><td><code>sovrn.com</code></td></tr><tr><td>TripleLift</td><td><code>triplelift.com</code></td></tr><tr><td>Equativ / Smart</td><td><code>smartadserver.com</code></td></tr><tr><td>ImproveDigital</td><td><code>improvedigital.com</code></td></tr><tr><td>Freewheel</td><td><code>freewheel.com</code></td></tr><tr><td>OneTag</td><td><code>onetag.com</code></td></tr><tr><td>RTB House</td><td><code>rtbhouse.com</code></td></tr><tr><td>Aidem</td><td><code>aidem.com</code></td></tr><tr><td>Nexxen / Unruly</td><td><code>unrulymedia.com</code></td></tr><tr><td>33Across</td><td><code>33across.com</code></td></tr><tr><td>ConnectAd</td><td><code>connectad.io</code></td></tr><tr><td>E-Planning</td><td><code>e-planning.net</code></td></tr><tr><td>Illumin / AcuityAds</td><td><code>acuityads.com</code></td></tr><tr><td>Insticator</td><td><code>ingage.tech</code></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://adagio-io.gitbook.io/adagio-documentation/openrtb-s2s-endpoint/user-synchronization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.