Buyer User Matching

User matching, or cookie syncing, is the process of matching a Supplier’s cookie ID to a Buyer’s cookie ID. BidSwitch has an integrated user matching functionality to facilitate this between Buyers and Suppliers. User matching information is managed within the BidSwitch database, so there is no need for Buyers to implement user matching logic to store user mappings.

When sending bid requests to the Buyer, BidSwitch will send the Buyer User ID and the BidSwitch User ID in the user.buyeruid and user.id fields of the User Object. You may also receive extended identifiers in the user.ext.eid field.

Note

• If the user ID is not available, then only the BidSwitch user ID will be sent. There can be cases when the BidSwitch ID is not available either, and consequently neither ID can be sent to the DSP.

• To sync app users, see the In-App User Optimization section.

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", } }

Buyer Initiated User Matching

To sync a particular user with BidSwitch, the Buyer should redirect the user’s browser call to the BidSwitch sync URL, https://x.bidswitch.net/sync, expecting to receive a 1x1 .gif image as a result, and provide the following HTTP request parameters specifying their relevant values.

Important

• You should always use HTTPS connections when user syncing, because since Chrome 80 site owners need to explicitly label third-party cookies with SameSite=None; Secure in order to use them on other sites, and insecure connections (http) can’t set cookies with the Secure directive.

• You can add all macros to one URL, i.e. you can add CCPA and GDPR macros to one URL. The values will only be filled when relevant to the user context.

• 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 the HTTP Request Parameters table.

HTTP Request Parameters

Key	Type	Value Description
dsp_id	string	(Required) The ID assigned to the Buyer by BidSwitch, for example, 123.
user_id	string	(Required) The User ID in the Buyers’s system, for example abc-456. The User ID can be a maximum of 50 characters. If you do not have a user_id for the user, e.g. users on Safari, you should respond with a 302 redirect to the BidSwitch sync URL with an empty user_id parameter, see the Users without Cookies section.
expires	integer	(Optional) Expiration time in days for user matching, for example 5. The default value is 90. See the Cookie Syncing Best Practices section about how to get the most out of user matching.
user_group*	integer	(Optional) Sets the user group with which to sync this user. The valid values for user groups are 1 - 99, with 1 being the default value. See the User Group Syncing section for more details.
gdpr	string	(Optional) Indicated 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. You can also use a macro in your user sync URL with BidSwitch to have the Supplier value returned. If this is used, BidSwitch will return the GDPR information in it GDPR=${GRPR}
gdpr_consent	string	(Optional) A URL-safe base64-encoded GDPR consent string, which encodes the consented-to purposes and vendor consent string, as obtained from the CMP JS API or OpenRTB. You can also use a macro in your user sync URL with BidSwitch to have the Supplier value returned. If this is used, BidSwitch will return the GDPR information it got from the Supplier for this user, e.g. GDPR=${GDPR_CONSENT} BidSwitch supports the v1.1 and v2.0 consent string formats. For each version the format of this macro differs slightly v1.1 ${GDPR_CONSENT} is filled with the user consent string v2.0 ${GDPR_CONSENT_XXX} is filled with the user consent string, where XXX if the GVL ID, e.g. ${GDPR_CONSENT_128} See the BidSwitch and GDPR section for more details. Notes: If BidSwitch does not have consent to process a user it will not sync the user. This is only meaningful if GDPR applies, i.e. gdpr=1.
us_privacy	string	(Optional) 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.
_origin	string	(Optional) This parameter can be used with the following macro ${BSW_ORIGIN_INIT}. If present in your sync URL, BidSwitch will return 0 for syncs initiated by you and 1 for BidSwitch initiated syncs. For example: //dsp.sync.url/sync?uid=${UUID}&_origin=${BSW_ORIGIN_INIT}

# User sync - HTTPS
https://x.bidswitch.net/sync?dsp_id=123&user_id=1234567890&expires=30

## User sync and assigning to a user group - HTTP
https://x.bidswitch.net/sync?dsp_id=1&user_id=1235ABC&expires=30&user_group=5

## User sync with GDPR consent - HTTPS
https://x.bidswitch.net/sync?dsp_id=1&user_id=1235ABC&expires=30&user_group=5&gdpr=1&gdpr_consent=Y29uc2VudCBkYXRh

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

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.

• Set the BidSwitch cookie expiration date to less than 30 days. Ideally between 5 - 10 days. This will enable the Supplier to cookie sync with BidSwitch more often.

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

User Group Syncing

During cookie syncing, when a Buyer sends their cookie ID to BidSwitch, it is possible to append the user_group parameter to the pixel. This specifies in which group BidSwitch should place the user for SmartSwitch filtering.

Supplier Initiated Cookie Sync Response:

## Syntax
https://x.bidswitch.net/sync?dsp_id=[DSP_ID]&user_id=[DSP_COOKIE_ID]&expires=30&ssp=[SSP_NAME]&user_group=[NUMERICAL_VALUE]

## Example
https://x.bidswitch.net/sync?dsp_id=1&user_id=1235ABC&expires=30&ssp=rubicon&user_group=5

Buyer initiated cookie sync:

## Syntax
https://x.bidswitch.net/sync?dsp_id=[DSP_ID]&user_id=[DSP_COOKIE_ID]&expires=30&user_group=[NUMERICAL_VALUE]

## Example
https://x.bidswitch.net/sync?dsp_id=1&user_id=1235ABC&expires=30&user_group=5

See also

• To learn more about SmartSwitch, see the SmartSwitch Overview section.

• To learn about how user groups can improve the quality of inventory in your BidStream, see the SmartSwitch User Optimization section.

• For in-app syncing, see the In-App User Optimization section.

BidSwitch Initiated User Matching

Brief Overview

1. The Buyer provides an endpoint to BidSwitch that can handle the ${SSP} and ${BSW_PARAM} required macros.

2. BidSwitch syncs with this endpoint, filling in the ${SSP} value, and depending on the user syncing context BidSwitch may also fill in the custom parameter macro ${BSW_PARAM}.

3. The Buyer responds with their information for this user, which is stored by BidSwitch and synced with the Supplier.

Providing a Usable Endpoint

BidSwitch can initiate user synchronization once the partner issues BidSwitch with the aforementioned matching URL that redirects to the pixel URL described in the Buyer Initiated User Matching section, with the required macros properly populated (${dsp_id}, ${user_id}, and ${ssp}), and if applicable the optional macros (${expires}, ${user_group}, ${bsw_param}, ${GDPR}, ${GDPR_PD}, ${GDPR_CONSENT}, and ${US_PRIVACY})

Note

This URL should be for a pixel that performs a 302 redirect, rather than an iframe with a script inside it. The only redirect from the Buyer matching URL should be to the BidSwitch pixel.

The matching redirect URL, issued by the Buyer should contain the ${SSP} macro, and if needed the ${BSW_PARAM} macro. These macros are substituted with values by BidSwitch before sending a user to the partner for syncing. The values sent in these macros should be returned to BidSwitch, as in the following example matching URL.

 # The XXX in the consent macro should match your Global Vendors List (GVL) ID
 https://dsp-example.com/bidswitch/cm?bidswitch_ssp_id=${SSP}&gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT_XXX}&us_privacy=${US_PRIVACY}

# Example Buyer URL with additional macro for cookie-less user sync
https://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=${SSP}&bsw_custom_parameter=${BSW_PARAM}&gdpr=${GDPR}&gdpr_consent=${GDPR_CONSENT}

Hint

The bidswitch_ssp_id and bsw_custom_parameter names can be changed to any other name chosen by the Buyer.

How BidSwitch Syncs a User with this Endpoint

When BidSwitch sends a call to the Buyer matching URL, it will take the following form.

# Example DSP Call
https://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=rubicon&us_privacy=1YNY

# Example DSP call with additional param
https://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=rubicon&bsw_custom_parameter=abcd1234

How the Buyer should respond to the call

On receiving a call to the above URL, the partner server should respond with a 302 redirect to the BidSwitch matching URL with the following valid values.

• dsp_id, user_id, and expires (optional) parameters as described in the Buyer Initiated User Matching section.

• Provide the Supplier name using the ${SSP} macro.

• Return the BidSwitch user ID in the ${BSW_PARAM} field, so that BidSwitch can map it to the user_id.

URL sync Parameters

Value	Type	Description
dsp_id	string	The ID assigned to the Buyer by BidSwitch, for example, 123.
ssp	string	The ID assigned to the Supplier by BidSwitch, for example, rubicon. This field should contain the ${SSP} value passed in the initial BidSwitch call.
user_id	string	The User ID in the Buyers’s system, for example 123456. If you do not have a user_id for the user, e.g. users on Safari, you should respond with a 302 redirect to the BidSwitch sync url with an empty user_id parameter, see the Users without Cookies section.
bsw_param*	string	Passes the BidSwitch User IDs in a comma-separated format in the event of cookie-less user syncing, for example 123456 or abc123,def345. This field should contain the bsw_custom_parameter value passed in the initial BidSwitch call.
expires*	integer	Sets the expiration time in days for user matching, for example 5. The default value is 90. See the Cookie Syncing Best Practices section about how to get the most out of user matching.
user_group*	integer	Sets the user group with which to sync this user. The valid values for user groups are 1 - 99, with 1 being the default value. See the User Group Syncing section for more details.

# Example DSP Return Call
https://x.bidswitch.net/sync?dsp_id=123&user_id=123&expires=5&ssp=rubicon

# Example DSP Return Call with additional param
https://x.bidswitch.net/sync?dsp_id=123&user_id=123&expires=5&ssp=rubicon&bsw_param=abcd1234,def345

Further Information for HTTP(S)

In addition to HTTP, the matching redirect URL provided by the partner should also support secure HTTPS connections. If BidSwitch initiates a user call using HTTPS protocol, the partner should redirect the user to the BidSwitch matching URL using a secure HTTPS connection. And vice versa, if BidSwitch initiates a user call using HTTP protocol, the partner should redirect the user to the BidSwitch matching URL using a non-secure HTTP connection.

After BidSwitch initiates user matching, it associates the value of the user_id parameter with the user’s browser and makes it available in any later bid requests from this user’s browser. This will be sent in the buyeruid field of the JSON bid request.

Note

The user_id should not exceed 36 characters.

Users without Cookies

For users without cookies, e.g those using Safari, you can sync them without a user_id value by using a 302 redirect to the BidSwitch sync URL. BidSwitch uses the returned call to store the information about the user ID missing at the target Buyer and then forwards the call to the SSP it originated from.

All of the additional parameters outlined in the BidSwitch Initiated User Matching should be returned, including ssp and bsw_param if supported.

https://x.bidswitch.net/sync?dsp_id=123&user_id=&expires=5&ssp=rubicon

# Example DSP Return Call with additional param
https://x.bidswitch.net/sync?dsp_id=123&user_id=123&expires=5&ssp=rubicon&bsw_param=abcd1234

User Syncing FAQ

How do I delete a user group?

A user group will be deleted automatically if it doesn’t contain any users, or all users are expired.

How do I remove users from a group?

You can sync the users in question with a new user group reserved for unwanted users, for example user_group=5

Once set, will our feed include only bid requests from those user groups?

No, the user group is only 1 parameter among others such as geo, ssp, publisher, site, domain, etc. See the SmartSwitch Overview section for more information. Each of these parameters is important and the user_group is only one amongst the others.