Supplier User Matching

As the Supplier and BidSwitch sit between the end-user and the Buyer, user matching is important as it allows a Buyer to know the potential value of a user, and thus make calculated decisions to serve the most appropriate advertisements. Additionally, it can increase CPM and media spend to Suppliers. It is therefore in both parties best interests to sync their cookies appropriately. Use the information in the following sections to get the most out of user matching.

Bid Request Fields

User matching, or cookie syncing, is the process of matching a Supplier cookie ID to a Buyer cookie ID. BidSwitch has an integrated user matching functionality to facilitate this between Buyers and Suppliers. When receiving a bid request from a Supplier, BidSwitch expects both the BidSwitch User ID and Supplier User ID to be sent in the user.buyeruid and user.id fields of the User Object.

Supplier Buyer User Matching

Supplier to BidSwitch Bid Request	BidSwitch to Buyer Bid Request
{ "user":{ "id":"ssp-cookie-1234", "buyeruid":"bsw-cookie-54321", } }	{ "user":{ "id":"bsw-cookie-54321", "buyeruid":"DSP-cookie-5678", } }

Supplier User Matching Flow

When all parties have synced their cookies, bid requests from the Supplier to BidSwitch will contain the BidSwitch cookie ID. BidSwitch will then match and retrieve the Buyer cookie ID from the BidSwitch database and send it to the correct Buyer. This enables the Buyer to use their cookie ID and bid intelligently.

Supplier Initiated User Sync

Suppliers should sync users using the BidSwitch user sync URL. Once synced, BidSwitch redirects the user to the Supplier’s sync URL, this endpoint is completely up to the Supplier and you can check what link BidSwitch is syncing with on the UI Settings page. This URL can also contain a number of macros, which BidSwitch will fill with values if it is applicable and has those values, e.g. {US_PRIVACY}, see the Supported Sync Macros section for more details.

Supplier Initiated Cookie Sync Endpoint

## Syntax
https://x.bidswitch.net/sync?ssp=${SSP_NAME}&user_id=${SSP_UID}

## Example
https://x.bidswitch.net/sync?ssp=sspname&user_id=user12345

## User sync with GDPR consent
https://x.bidswitch.net/sync?ssp=sspname&user_id=1235AB&gdpr=1&gdpr_consent=Y29uc2VudCBkYXRh

## User sync with US Privacy consent - HTTPS
https://x.bidswitch.net/sync?ssp=sspname&user_id=1235ABC&expires=30&us_privacy=1YYN

Note

Fields marked with asterisk (*) are optional.

HTTP Request Parameters

Key	Type	Description
ssp_id	string	The ID assigned to the Supplier by BidSwitch, for example, sspname.
gdpr*	string	Indicates if GDPR applies to this sync. GDPR=0 does not apply GDPR=1 applies. If this field is not supplied, the callee should perform a geoIP lookup as GDPR applies for EU IP addresses.
gdpr_pd*	int	Indicates whether generic URL parameters contain personal data, 0 for no, 1 indicates personal data
gdpr_consent*	string	A URL-safe base64-encoded GDPR consent string. Only meaningful if gdpr=1. Encodes the purposes to which the user consented and the vendors to whom the user gave that consent, as obtained from the CMP JS API or OpenRTB. The v1.1 {GDPR_CONSENT} or v2.0 {GDPR_CONSENT-GVL_ID} macro is filled with the consent string. As 2.0 is now the only valid consent string, a v2.0 string will be filled for each macro. The v1.1 is supported for backward compatibility Note: If BidSwitch does not have consent to process this user it will not sync the user. Only meaningful if gdpr=1. Also macro only refers to what is within curly braces, e.g. ${GDPR_CONSENT}. When referring to a macro or its value in a URL, you should not confuse them with the keys that refer to them, e.g. example.url/?key=value, key in this URL refers to a value which could be a macro. Only use the keys outlined in this table to refer to macros or their value.
us_privacy*	string	Passes the CCPA compliant US Privacy string that indicates whether the user has “opted-in” or “opted-out” of the sale of their data, e.g. us_privacy=1NNY. For more information, see the BidSwitch and CCPA section.
user_id*	string	The Supplier user ID. This is the value normally passed in the user.id field in OpenRTB bid requests. Note: This parameter is highly recommended for browsers that do not support 3rd party cookies, e.g. Safari and IOS_App.
expires*	integer	The cookie lifetime in days

Cookie Syncing Best Practices

While it is also the responsibility of Buyers to play an active part in the cookie syncing process, BidSwitch strongly recommends the following Supplier practices to maximise ROI.

• If there is any cookie logic, ensure that BidSwitch is set with a high priority.

• Aim to cookie sync user data with BidSwitch once per day.

• Set the BidSwitch cookie expiration date to more than 30 days. Ideally closer to 365 days. This will prevent BidSwitch from storing a lot of expired user IDs and increase the sync rate with the Supplier.

BidSwitch Initiated User Sync

When BidSwitch initiates a user sync with a Supplier, the process flows in the following manner.

1. The user lands on a page, which runs a Buyer tag.

2. Running this Buyer tag drops a cookie to the user browser e.g. DSP_cookie_9876, which redirects to BidSwitch.

3. BidSwitch stores the Buyer cookie ID, e.g. DSP_cookie_9876.

4. BidSwitch then redirects to a sync pixel belonging to a Supplier connected to the Buyer.

5. The Supplier receives the BidSwitch cookie ID for this user, e.g. BSW_cookie_54321.

6. The Supplier matches the BidSwitch cookie ID with its cookie ID, and stores them in their database.

Supported Sync Macros

When you provide your sync URL to BidSwitch, it can contain the following macros that BidSwitch will replace with values if it has them, e.g. ${US_PRIVACY} will be replaced by the CCPA string for that user, e.g. 1NNY

Supplier Sync URL examples with macros

example-ssp.com/sync?userid=${UUID}&gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT}&us_privacy=${US_PRIVACY}

Sync URL macros

Value	Description
${UUID}	Returns the User ID for example abc-456. The User ID can be a maximum of 50 characters.
${GDPR}	Indicates if GDPR applies to this sync. GDPR=0 does not apply GDPR=1 applies.
${GDPR_CONSENT}	Returns the GDPR consent string associated with the user. BidSwitch supports the v1.1 and v2.0 consent string formats. For each version the format of this macro differ slightly v1.1 ${gdpr_consent} is filled, which will match the user consent string v2.0 ${gdpr_consent_GVL-ID} is filled, which will match the user consent string. See the BidSwitch and GDPR section for more details. Note: If BidSwitch does not have consent to process this user it will not sync the user. Only meaningful if gdpr=1.
${GDPR_PD}	Indicates whether generic URL parameters contain personal data, 0 for no, 1 indicates personal data
${US_PRIVACY}	Passes the CCPA compliant US Privacy string that indicates whether the user has “opted-in” or “opted-out” of the sale of their data, e.g. 1NNY. For more information, see the BidSwitch and CCPA section.