Server-side user cookie sync up (SSP Ad Server)

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Aug 24, 2017
Version 4Show Document
  • View in full screen mode

Server-side cookie sync up is mandatory while integrating with PubMatic APIs on the server side (server-to-server APIs). Since there is no access to the browser's cookies as the ad serving request is sent from the server, the below mechanism will help in obtaining the PubMatic user IDs, storing it in a server-side cookie store.

 

A mapping between the publisher's user ID and the PubMatic user ID should be stored in the publisher's server-side cookie store.

Let's say, http://publisher.com/keepUserMap.php?pmUserId= is a service used by the publisher to keep a mapping of the user IDs. Let's assume that the publisher's user ID is stored on a user's browser in a cookie named "pub-user-id" with value "PUB_UserID_9890". Now if above URL is passed as http://publisher.com/keepUserMap.php?pmUserId=PM_UserID_2200 then the publisher should map his user ID (PUB_UserID_9890) and PubMatic's user ID (PM_UserID_2200).

 

To encode such a URL as http%3A%2F%2Fpublisher.com%2FkeepUserMap.php%3FpmUserId%3D, you can use the following JavaScript code - encodeURIComponent('http://publisher.com/keepUserMap.php?pmUserId=');

 

PubMatic's "user_sync.html" can call a given publisher's URL and append the PubMatic user ID to the publisher URL as mentioned below.

While sending a bid request to the PubMatic ad server, you may look up the PubMatic user ID in the cookie store and send it as a part of the request header. To do sync up-pixeling, the publisher should call the following URL in iframe on every page hit.

New URL to be used: http://ads.pubmatic.com/AdServer/js/user_sync.html?p=31445&s=21446&predirect=http%3A%2F%2Fpublisher.com%2FkeepUserMap.php%3FpmUserId%3D

Where "p" indicates the publisher's ID, "s" indicates the site ID and "predirect" indicates the third-party user ID sync up URL to be called by PubMatic for the user sync up. However, site ID is an optional parameter.

Old URL to be deprecated: http://ads.pubmatic.com/AdServer/js/user_sync.html?predirect=EXTERNAL_URL

 

Workflow:

  • If the client ad request does not have the user cookie for PubMatic, please send a call to the above-mentioned URL with a beacon of your domain as a value to the "predirect" parameter.
  • The above call will create a PubMatic user ID, if it does not exist already.
  • The generated PubMatic user ID will be appended to the third-party URL that was sent as ‰ŰĎpredirect‰Űť parameter's value in the above call.
  • This PubMatic user ID should be mapped to the third party user ID and then passed in the KADUSERCOOKIE parameter in the request's header to PubMatic in the next bid request.
  • For the user ID sync up with our data partners, you need to call the above URL multiple times.

 

Passing PubMatic user ID in request header

The PubMatic user ID should be sent in the request header as a cookie key-value pair. The user cookie key name is KADUSERCOOKIE.

For example, Cookie:KADUSERCOOKIE=F6FC89B0-54AE-46E1-A5FF-10336B7A8E26;

Attachments

    Outcomes