This endpoint is used to initiate cookie syncs.
Generally, two clients invoke the /cookie_sync endpoint:
The example request below returns a set of URLs to enable cookie syncs across bidders. The request must supply a JSON object to define the list of bidders that may need to be synced.
POST request:
{
"bidders": ["bidderA", "bidderB"],
"gdpr": 1,
"gdpr_consent": "BONV8oqONXwgmADACHENAO7pqzAAppY"
}
Response:
{
"status": "ok",
"bidder_status": [
{
"bidder": "bidderA",
"usersync": {
"url": "someurl.com",
"type": "redirect",
"supportCORS": false
}
}
]
}
The client code is responsible for taking the url
response parameter and invoking it in the appropriate way. For example:
type
is “redirect”, place an img
tag in the pagetype
is “iframe”, place an iframe
tag in the pageName | Scope | Description | Example | Type |
---|---|---|---|---|
bidders | optional | array of bid adapters in the page or those the publisher wishes to sync with | [“bidderA”] | array of strings |
gdpr | optional | flag indicating whether the request is in-scope for GDPR processing | 1 | 0 or 1 |
gdpr_consent | optional | GDPR consent string from the CMP | string | |
limit | optional | number indicating the max number of sync URLs to return | 5 | integer |
coopSync | optional | (PBS-Java only) Cooperative syncing is a way for publishers to help each other by allowing PBS to sync bidders beyond those specified by the bidders argument. See below for details. The default depends on PBS host company settings. |
true | boolean |
filterSettings | optional | object defining which types of syncs are allowed for which bidders. Modeled after the similar Prebid.js feature. | object | |
filterSettings.iframe | optional | define the filter settings for iframe syncs | object | |
filterSettings.image | optional | define the filter settings for redirect syncs | object | |
filterSettings. iframe/image.bidders | optional | define which bidders are in scope for this setting. Can be “*” | [“bidderA”] | array of strings or “*” |
filterSettings. iframe/image.filter | optional | define whether to include or exclude the named bidders for this entry. May be “include” or “exclude”. Defaults to “include” | “exclude” | string |
Here’s how PBS determines which bidders to sync:
bidders
parameter.bidders
parameter, assume all known bidders.limit
parameter if suppliedlimit
and coopSync
is true, randomly add more unsynced bidders until the limit is reached.gdpr
is optional. It should be 1 if GDPR is in effect, 0 if not, and omitted if the caller is unsure.
gdpr_consent
is required if gdpr
is 1
, and optional otherwise. If present, it should be an unpadded base64-URL encoded Vendor Consent String.
If gdpr
is omitted, callers are still encouraged to send gdpr_consent
if they have it.
Depending on how the Prebid Server host company has configured their servers, they may or may not require it for cookie syncs.
This is a flexible setting based on the Prebid.js feature of the same name that allows publishers control over which bidders are allowed to drop iframes vs images.
It could be specified in a detailed way like this:
filterSettings: {
iframe: {
bidders: ['def'], // only this bidder is excluded from syncing iframe pixels, all other bidders are allowed
filter: 'exclude'
},
image: {
bidders: ['abc', 'def', 'xyz'], //only these 3 bidders are allowed to sync image pixels
filter: 'include'
}
},
But the main use case for Prebid Server is what load-cookie.html does in AMP, which is to disallow iframes:
filterSettings: {
iframe: {
bidders: '*',
filter: 'exclude'
}
},