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. Note: To sync app users, see the In-App User Optimization section.

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.

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

Note

If the user ID is not available, then only the BidSwitch user ID will be sent. There are cases when the BidSwitch ID is not available either, in this case neither ID can be sent to the DSP.

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 the value is an empty string, the user is considered unmatched and no further sync requests are sent for this user, for the duration of the time set with the expires parameters. See Not Syncing Certain Users for more details.
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 0 - 5, with 0 always being considered unmatched users in BidSwitch. See the User Group Syncing section for more details.
# User sync
https://x.bidswitch.net/sync?dsp_id=123&user_id=1234567890&expires=30

# Do Not User Sync
# Redirecting a user to the following URL will not sync the
# specified user for the next 5 days, and will consider bids
# from this user as user-unmatched for the given DSP
http://x.bidswitch.net/sync?dsp_id=123&user_id=&expires=5

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 which group BidSwitch should place the user in 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

Not Syncing Certain Users

A Buyer may differentiate between valuable and not valuable users. The latter are usually users that don’t have any re-targeting or third party data recorded for them. It is highly recommended that in the case of a sync request for a not valuable user, the Buyer responds with a 302 redirect to the BidSwitch sync url with an empty user_id parameter, for example,

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

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 the above mentioned matching URL that redirects to the pixel URL described in the Buyer Initiated User Matching section, with properly populated required parameters (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 for an iframe with a script inside it. The only redirect from the Buyer’s 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, provided by the partner.

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

# Example DSP 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}

Here, the bidswitch_ssp_id and bsw_custom_parameter parameters name can be changed to any other name chosen by the Buyer.

How BidSwitch Syncs and User with this Endpoint

When BidSwitch sends a call to the partner matching URL 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 Buyer by BidSwitch, for example, 123. 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 the value is an empty string, the user is considered unmatched and no further sync requests are sent for this user, for the duration of the time set with the expires parameters. See Not Syncing Certain Users for more details.
bsw_param* string Used to pass the BidSwitch User ID in the event of cookie-less user syncing. This field should contain the ${BSW_PARAM} value passed in the initial BidSwitch call
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 0 - 5, with 0 always being considered unmatched users in BidSwitch. 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.

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, or you can sync users with the option user_group=0 to place them in the unsynced user group.
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.