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 both the Buyer User ID and the BidSwitch User ID in the buyeruid and id fields of the User Object.

../_images/cookie-sync-bsw.svg

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 to the BidSwitch sync URL, http://x.bidswitch.net/sync, expecting to receive a 1x1 .gif image as a result, and provide the following HTTP request parameters.

Note

  • The BidSwitch matching URL also supports secure HTTPS connections.
  • Fields marked with asterisk (*) are optional.
HTTP Request Parameters
Value Type Description
dsp_id string The ID assigned to the Buyer by BidSwitch, for example, 123.
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.
expires* integer 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 - 5, with 1 being the default value. See the User Group Syncing section for more details.
gdpr* string Indicated if GDPR applies to this sync. 0=GDPR does not apply 1=GDPR applies. If this field is not supplied, the callee should perform a geoIP lookup as GDPR applies for EU IP addresses.
gdpr_consent* string A URL-safe base64-encoded GDPR consent string. Only meaningful if gdpr=1. Encodes the consented-to purposes and vendor consent string, as obtained from the CMP JS API or OpenRTB.
# User sync
https://x.bidswitch.net/sync?dsp_id=123&user_id=1234567890&expires=30

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

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

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

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
http://x.bidswitch.net/sync?dsp_id=[DSP_ID]&user_id=[DSP_COOKIE_ID]&expires=30&ssp=[SSP_NAME]&user_group=[NUMERICAL_VALUE]

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

Buyer initiated cookie sync:

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

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

See also

BidSwitch Initiated User Matching

Brief Overview

  1. The Buyer provides an endpoint to BidSwitch that can handle the $SSP and $BSW_PARAM values.
  2. BidSwitch syncs with this endpoint, filling in the $SSP value, and the Buyer responds with the user syncing details for their user. 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 above mentioned matching URL that redirects to the pixel URL described in the Buyer Initiated User Matching section, with the required parameters properly populated (dsp_id, user_id, and ssp), and if applicable, the optional parameters (expires, user_group, and bsw_param)

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 a Buyer should contain the ${SSP} and ${BSW_PARAM} macros. These macros are substituted on the BidSwitch side before sending a user to the partner. The values sent in these macros should be returned to BidSwitch, as in the following example matching URL.

# Example Buyer URL
http://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=${SSP}

# Example Buyer URL with additional param for cookie-less user sync
http://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=${SSP}&bsw_custom_parameter=${BSW_PARAM}

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
http://www.dsp-example.com/bsw_sync?bidswitch_ssp_id=rubicon

# Example DSP call with additional param
http://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 ID in the event of cookie-less user syncing. 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 - 5, with 1 being the default value. See the User Group Syncing section for more details.
# Example DSP Return Call
http://x.bidswitch.net/sync?dsp_id=123&user_id=123&expires=5&ssp=rubicon

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

Further Information

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.

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.

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

# Example DSP Return Call with additional param
http://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.