Configure User Syncing
The user sync configuration options described in this section give publishers control over how adapters behave with respect to dropping pixels or scripts to cookie users with IDs. This practice is called “user syncing” because the aim is to let the bidders match IDs between their cookie space and the DSP’s cookie space. There’s a good reason for bidders to be doing this – DSPs are more likely to bid on impressions where they know something about the history of the user. However, there are also good reasons why publishers may want to control the use of these practices:
  • Page performance: Publishers may wish to move ad-related cookie work to much later in the page load after ads and content have loaded.
  • User privacy: Some publishers may want to opt out of these practices even though it limits their users’ values on the open market.
  • Security: Publishers may want to control which bidders are trusted to inject images and JavaScript into their pages.
Note: User syncing default behavior If you don’t tweak any of the settings described in this section, the default behavior of Prebid.js is to wait 3 seconds after the auction ends, and then allow every adapter to drop up to 5 image-based user syncs.
pbjs.setConfig({
    userSync: {
        syncDelay: 5000 // write image pixels 5 seconds after the auction
    }
});
Arguments:
  • userSync: object

    Object containing values for user sync configurations.

    Accepted Values
    Attribute Type Description
    syncEnabled Boolean Enable/disable the user syncing feature. Default setting is true.
    filterSettings Object Configure lists of adapters to include or exclude their user syncing based on the pixel type (image/iframe).
    syncsPerBidder Integer Number of registered syncs allowed per adapter. Default setting is 5. To allow all, set to 0.
    syncDelay Integer Delay in milliseconds for syncing after the auction ends. Default setting is 3000.
    enableOverride Boolean Enable/disable publisher to trigger user syncs by calling pbjs.triggerUserSyncs(). Default setting is false.
User Sync Examples
Examples of configurations that will change the default behavior:

Push the user syncs to later in the page load.

pbjs.setConfig({
	    userSync: {
	        syncDelay: 5000 // write image pixels 5 seconds after the auction
	    }
	});

Turn off user syncing entirely.

pbjs.setConfig({
    userSync: {
        syncEnabled: false
    }
});

Allow iframe-based syncs (the presence of a valid filterSettings.iframe object automatically enables iframe type user-syncing).

pbjs.setConfig({
    userSync: {
        filterSettings: {
            iframe: {
                bidders: '*',   // '*' means all bidders
                filter: 'include'
            }
        }
    }
});
Note - iframe-based syncing is disabled by default. Image-based syncing is enabled by default; it can be disabled by excluding all/certain bidders via the filterSettings object.

Only certain bidders are allowed to sync and only certain types of sync pixels.

pbjs.setConfig({
    userSync: {
        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'
            }
        },
        syncsPerBidder: 3, // and no more than 3 syncs at a time
        syncDelay: 6000, // 6 seconds after the auction
    }
});

If you want to apply the same bidder inclusion/exlusion rules for both types of sync pixels, you can use the all object instead specifying both image and iframe objects like so:

pbjs.setConfig({
    userSync: {
        /* only these bidders are allowed to sync.  Both iframe and image pixels are permitted. */
        filterSettings: {
            all: {
                bidders: ['abc', 'def', 'xyz'],
                filter: 'include'
            }
        },
        syncsPerBidder: 3, // and no more than 3 syncs at a time
        syncDelay: 6000, // 6 seconds after the auction
    }
});
Note - the all field is mutually exclusive and cannot be combined with the iframe/image fields in the userSync config. This restriction is to promote clear logic as to how bidders will operate in regards to their userSync pixels. If the fields are used together, this will be considered an invalid config and Prebid will instead use the default userSync logic (all image pixels permitted and all iframe pixels are blocked).

The same bidders can drop sync pixels, but the timing will be controlled by the page.

pbjs.setConfig({
    userSync: {
        /* only these bidders are allowed to sync, and only image pixels */
        filterSettings: {
            image: {
                bidders: ['abc', 'def', 'xyz'],
                filter: 'include'
            }
        },
        enableOverride: true // publisher will call `pbjs.triggerUserSyncs()`
    }
});

As noted, there’s a function available to give the page control of when registered user syncs are added.

pbjs.triggerUserSyncs();
How user syncing works
The userSync.registerSync() function called by the adapter keeps a queue of valid userSync requests. It prevents unwanted sync entries from being placed on the queue:

When user syncs are run, regardless of whether they are invoked by the platform or by the page calling pbjs.triggerUserSyncs(), the queue entries are randomized and appended to the bottom of the HTML tag.
Response
Response Description
{ response: example }
  • param1: string

    String indicating some value that has to be passed as a string type.

  • param2: number

    Number indicating some value that has to be passed as a number type.

    Note: This number should be between 0 and infinity.