User Match Transition Guide for Partners

Usermatch process

What is user matching?
User matching (cookie syncing) is the process of syncing browser-based user IDs (cookies) between Audience Studio and the partner system.

What is a user match table?
In order to implement the user match, a user match table is developed, which essentially preserves the mapping of a KUID (i.e Krux User ID) to the corresponding partner user id.

How is user match table currently populated by Audience Studio?
Whenever a usermatch pixel is fired on a partner’s property, Audience Studio sends an API request to the partner with the Krux Id value. The partner then calls an API endpoint in Audience Studio to send the id of the user in partner’s universe, hereafter called as partnerUserId, id of partner hereafter called as partnerId along-with the required parameter like KUID.

This adds one entry in the user match logs for the partner.
The user match logs are parsed and aggregated table so formed is used as a lookup in the generation of the users segment map which is sent as part of incremental and full refreshes to activation partners.

What is partner hosted user matching and how does it differ from Salesforce hosted user matching?
For Salesforce hosted user match, Salesforce would store the partner’s user id mapped to kuid so that the partner’s id could be provided in data sent or received. In partner hosted user matching, Salesforce fires the partner’s user match pixel for mutual customers and returns the Salesforce Audience Studio user id (kuid) so the partner can store the partner user id (puid) mapped to the kuid for each cookie. Once transitioned to partner-hosted user match, Salesforce will include kuid in data sent to activation partners and will expect to receive kuid in third party data delivered to Salesforce.

Transitioning to Partner Hosted User Matching

The transition of usermatch from Salesforce to partners is planned to be implemented in two phases.

In the first phase , Salesforce will help implement a bi-directional user match in which the user match table will be hosted both Salesforce and the partner. This phase will last from the time of partner user match implementation to the date when SF ceases holding the UM table.

In the second phase, the partner alone will host the user match table (uni-directional user match) and Salesforce will stop sending the PartnerUserId (PUID) in the segment maps which are sent as incremental / full refreshes to the activation partners. PUIDs will be replaced by Audience Studio User Ids (KUIDs).

If the partner already hosts the usermatch table then no further action needs to be taken.
In other cases Salesforce needs the below information to configure the bi-directional user match process.

  1. Partner URL
  2. Param name in which Salesforce should send the KUID value.
  3. Beacon service redirect url param name
  4. Partner_UID placeholder information in the Salesforce Audience Studio beacon service url.
  5. All other optional params (gdpr, gdpr_consent, us_privacy). Let us know if you need these params, we will add those to your endpoint request url.

For example:

Let’s assume the partner name is AdPartner

And their end point is..

Here uid is the param where we will send the KUID cookie value. Partner needs to give Salesforce the endpoint and the param name in which Salesforce should send the KUID value.

Let’s come to the Beacon service url

When the partner receives the call to the above endpoint, they should send response to Salesforce’s beacon service, we see that most partners implement it either of these ways

  1. Through redirect url as a param in the above said endpoint
  2. Configuring the redirect in their system.

We let the partners to choose in which way they’d like to send this. But we’d like to help you configure this correctly.

Redirect Url

When the partner receives the endpoint hit, they’ll redirect to the below url to give the user’s id in the partner ecosystem.
And this id will be passed by replacing this ADPARTNER_UID string in the url

So the actual endpoint will redirect to

Note in the above url the redirect url param name is redir, partner need to provide this info as well for successful configuration of user match tag.

To conclude the requirements in this method

  1. Partner endpoint url
  2. Parameter name in which the KUID value should be passed
  3. Salesforce beacon service redirect url param name
  4. Placeholder in the Salesforce url with which the partner will replace the userid during the redirect.

Redirect configuration in the partner end

Some partners use this method where, on receiving a request to the partner endpoint with the KUID, they’ll send a response to salesforce.

here partner param value is unique partner name, and the ADPARTNER_UID value should be the user id in partner ecosystem.

So the requirements in this method would be

  1. Partner endpoint url
  2. Parameter name in which the KUID value should be passed
  3. The Salesforce beacon service redirect should be configured as well in the partner ecosystem.
Have more questions? Submit a request


Article is closed for comments.