Page tree


Introduction

It is recommended that Publishers who place the user_sync.html as an iframe on their web pages to perform the PubMatic user sync-up should implement this userSync.js tag to meet GDPR compliance. Publishers should place the JS-based tag for user sync-up on each page that will serve inventory. This will operate even if placed in an iframe. The userSync.js accepts GDPR and user-consent parameters from a publisher as mentioned in userSync.js documentation.

  

Example of a user_sync.html Tag with GDPR Parameter

http://ads.pubmatic.com/AdServer/js/user_sync.html?p=156578&gdpr=1&gdpr_consent=ABCFETYFDJLNBFCV&predirect=http%3A
%2F%2Fpubmlisher.com%2FcookieSyncEndPoint%3Fpubmatic_uid%3D(PM_UID)‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Example of Asynchronous Tag

<script type="text/javascript">
        (function(){
            var script = document.createElement('script');
            script.async = true;
            script.type = 'text/javascript';
            script.src = 'https://ads.pubmatic.com/AdServer/js/userSync.js';
            script.onload = function(){
                PubMaticSync.sync({
                    pubId: 12345,
                    siteId: 43215,
                    delay: 1000,
                    url: 'http://pubmlisher.com/cookieSyncEndPoint?pubmatic_uid=(PM_UID)',
                    macro: '(PM_UID)',
                    gdpr: 1,
                    gdprConsent: 'ABCDEFGHIJKLMNOPQRST'
                });    
            }
            var node = document.getElementsByTagName('script')[0];
            node.parentNode.insertBefore(script, node);
        })();
</script>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍


Parameters

ParametersMandatoryDescription
pubIdYesPublisher ID assigned by PubMatic.
siteIdNo

Publisher's Site ID.

Default value = 0

delayNo

Time in milliseconds after which we will create an iframe for user sync-up. This tag will create an ifram asynchronously.

Default value = 0

If GDPR inventory is detected, the same delay will be used as a timeout for retrieving the user's consent. Recommendation is to set it at approximately 1000.

urlNoPublisher URL for which the publisher wants PubMatic to pass the PubMatic User ID. This URL should not be encoded.
macroNoThe string in the URL parameter that is expected to be replaced by the PubMatic User ID. If this parameter is not present, the PubMatic User ID will be appended at the end of the URL provided in the url parameter. 
gdpr

Not required for non-GDPR inventory.


Recommended for GDPR inventory.

Pass "1" if the inventory is GDPR-compliant; this will let PubMatic know that the inventory is GDPR-compliant.
gdprConsent

Not required for non-GDPR inventory.


Recommended for GDPR inventory.

Publishers can pass on the GDPR user-consent string directly for PubMatic consumption.



Example of synchronous tag

<script type="text/javascript" src="https://ads.pubmatic.com/AdServer/js/userSync.js">
</script>
<script type="text/javascript">
    PubMaticSync.sync({
        pubId: 12345,
        siteId: 43215,
        delay: 1000,
        url: 'http://publisher.com/cookieSyncEndPoint?pubmatic_uid=(PM_UID)',
        macro: '(PM_UID)',
        gdpr: 1,
        gdprConsent: 'ABCDEFGHIJKLMNOPQRST'
    });
</script>‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Recommendations

  • Use asynchronous tag rather than using synchronous tag for a better user experience.
  • For the delay parameter, the shorter the delay, the better the performance of the tag.
  • The tag should be loaded in head section of the page.

About the Macro Parameter 

What is macro parameter?

The publisher must mention a string-pattern in the URL that they expect PubMatic to replace with PubMatic’s user ID. This string pattern is also known as macro
At tag execution time this string pattern is unknown to our code (as it is dynamic, and different for every publisher) therefore, we ask each publisher to pass this string pattern in the tag against the macro parameter.


What if macro parameter is not passed?

If the macro parameter is not passed, then our tag does not know which string pattern from the URL needs to be replaced with PubMatic’s user ID, therefore the code will simply append the PubMatic User ID at end of the URL.