How to Implement the Lotame User ID Module in Pubmatic

updated 1 yr ago

OVERVIEW

PubMatic provides a cloud infrastructure platform for digital advertising for app developers and publishers. Details on implementing the Lotame Uuser ID Module in Pubmatic are detailed below.

OpenWrap is the Pubmatic enterprise wrapper solution for Prebid.js. The platform offers cloud-based UI without requiring development resources or code changes.

Pubmatic’s publisher tool to manage and administer their managed service wrapper is called Identity Hub.

To learn more about Pubmatic Openwrap and Identity Hub, and make direct support requests, please visit https://pubmatic.com/products/header-bidding/ and https://pubmatic.com/products/identity-hub/

For instructions on how to build custom from source and use the Prebid.org’s web based build tool see the article How to Build Prebid From Source to Include The Lotame Panorama User ID Module

Set up The Identity Hub

This section provides instructions for setting up Identity Hub. Refer to the section that corresponds to the wrapper you are using:

Publishers using OpenWrap
Publisher using Prebid wrappers
Publishers passing custom first-party data to consumers

It is recommended to use Identity Hub with Prebid version 2.44 and above as most of the bidder adapters have support for identity from this version onwards, and covers a majority of the ID vendors.

Publishers Using OpenWrap

This is a beta feature - contact your account manager to have it enabled for your account.

Navigate to Inventory > OpenWrap.
The Identity feature is located in the Partner Management, Profile Management, and Tag Management tabs.
Navigate to the Partner Management tab and select Add Partner.
Choose Identity for the Partner Type.
From the Partner drop-down menu, select the partner you want to integrate with.
Enter an Account Name.
PubMatic's Identity partners are affiliated with Prebid, so you can refer to Prebid's UserId Modules Parameter Documentation for the remaining fields. The only exception is the FirstPartyId module, which you can find below [tk link to FirstPartyId].
Click Save when you're done.
Navigate to the Profile Management tab and select Create Profile.
Select OpenWrap for Partner Type.
Select the latest STABLE release for Release Version.
Select Enabled for Identity Module. Then select the identity partner you just created in the previous steps.
You can choose Identity Consumers (additional wrappers that you want to send the identity data to) from the drop-down menu.
Refer to the OpenWrap user guide for instructions on uploading the mapping for your bidder partners. Once you've done that, you can push the profile to Staging and then Production.
Navigate to Tag Management. Select DFP for Ad Server Type and select your Wrapper Tag Type. You can now copy the tag and paste it onto your page.

Publishers Using Prebid Wrappers

This is a beta feature - contact your account manager to have it enabled for your account.

Navigate to Inventory > OpenWrap.
The Identity feature is located in the Partner Management, Profile Management, and Tag Management tabs.
Navigate to the Partner Management tab and select Add Partner.
Choose Identity for the Partner Type. From the Partner from the drop-down menu, select the partner you want to integrate with.
Enter an Account Name.
PubMatic's Identity partners are affiliated with Prebid, so you can refer to Prebid's UserId Modules Parameter Documentation for the remaining fields. The only exception is FirstPartyId module, which you can find below. [tk link to FirstPartyId]
Click Save when you're done.
Navigate to the Profile Management tab and select Create Profile.
Select Identity for Profile Type. This disables the bidder configuration and displays only the Identity configuration.
Enter a Profile Name and then select a Release Version of 17.3.0 or above from the drop-down.
From the Identity Partners drop-down menu, select the partner(s) you want to integrate with.
You can also choose Identity Consumers (additional wrappers that you want to send the identity data to) from the drop-down menu.
Navigate to the Tag Management tab and select either OpenWrap or Identity for Profile Type. You can also do a combination of both wrappers. This will send IDs to all the wrappers.

Sample Layouts

For identity-only profile types, refer to sample page integrations for EB, TAM, and Prebid that display under Document Layout when selected.

Prebid wrapper demo and sample

Below is a link to the Prebid and Identity Hub demo and code sample.

Prebid and Identity Hub demo

https://jsfiddle.net/abhinavsinha/g5f08bmk/

Prebid wrapper code sample

<!-- IdentityHub Script begins here -->
      <script type="text/javascript">
     var PWT={}; //Initialize Namespace
     var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     var googletag = googletag || {};
     googletag.cmd = googletag.cmd || [];
     var gptRan = false;
     PWT.jsLoaded = function(){ //PubMatic pwt.js on load callback is used to load GPT and Prebid
       loadPrebidAndGPT();
     };
     var loadPrebidAndGPT = function() {
       // Check the gptRan flag
       if (!gptRan) {
         gptRan = true;
         var gads = document.createElement('script');
         var useSSL = 'https:' == document.location.protocol;
         gads.src = (useSSL ? 'https:' : 'http:') + '//www.googletagservices.com/tag/js/gpt.js';
         var node = document.getElementsByTagName('script')[0];
         node.parentNode.insertBefore(gads, node);
         var pbjsEl = document.createElement("script");
         pbjsEl.type = "text/javascript";
         pbjsEl.async = true;
         pbjsEl.src = "<PREBID.JS>"; //Your Prebid JS URL
         var pbjsTargetEl = document.getElementsByTagName("head")[0];
         pbjsTargetEl.insertBefore(pbjsEl, pbjsTargetEl.firstChild);
       }
     };
     // Failsafe to call prebid & gpt
    setTimeout(loadPrebidAndGPT, 100);
    </script>
    <script type="text/javascript">
      (function() {
        var purl = window.location.href;
        var url = '//ads.pubmatic.com/AdServer/js/pwt/PUBID/PROFILEID/'; //Replace with yor publisher Id and profile Id
        var profileVersionId = '';
        if(purl.indexOf('pwtv=')>0){
          var regexp = /pwtv=(.*?)(&|$)/g;
          var matches = regexp.exec(purl);
          if(matches.length >= 2 && matches[1].length > 0){
            profileVersionId = '/'+matches[1];
          }
        }
        var wtads = document.createElement('script');
        wtads.async = true;
        wtads.type = 'text/javascript';
        wtads.src = url+profileVersionId+'/pwt.js';
        var node = document.getElementsByTagName('script')[0];
        node.parentNode.insertBefore(wtads, node);
      })();
    </script>
   <!--IdentityHub Script ends here -->

Publishers using non-supported third-party/custom wrappers

If you want to send IDs to a custom wrapper or endpoint, you can deploy the Identity-only Hub on the page as described in steps above.
Once the Hub executes, you can get all the IDs using the Javascript API/function call:

PWT.getUserIds()

This will return all the userIds in standard JSON object, which can be processed and sent to any consumer as needed.

{
 "criteoId": "n9fH3F83ZGdWeFVqRFZOdyUyRmMwbiUyRnNQbzdIdG9rZEgxN09WUXpHVGdETSUyRjBkSW",
 "pubcid": "273bc64a-c66e-4098-b165-XXXXXXX",
 "tdid": "027350a6-a756-4d85-a8f1-XXXXXXXXX"
}

Publishers passing custom first-party data to consumers

If you want to pass hashed email, hashed phone, or any other similar user data to wrapper/exchanges. Choose FirstPartyId from the drop-down menu when adding a new partner.
Generate a tag as described in one of the sections above (depending on your use case).
Define the function on the page where you expose hashed user data with the same name as defined in Function Name while adding a partner. Refer to FirstPartyId module below for details. [tk link to FirstPartyId below]

FirstPartyId module

FirstPartyID is PubMatic's proprietary module.

PARAMETER	DESCRIPTION	SAMPLE VALUES
Storage Type	The browser storage type where this data will be persisted For now only cookie is supported	cookie
Storage Expires	The time in days after which the value should be persisted. After expiry time module will try to update data	30
Storage Name	The name of cookie/local storage where this value will be persisted in user browser. Make sure its unique and doesn't conflict with other cookies	_myfirstPartyData
Function Name	This is the function that the module will call to get first party data. This function needs to be defined and present in window scope for this module to work. In response it expects a string / object which will be passed to wrapper and exchange partner	getFirstPartyData
Cookie Name	If publisher has first-party data stored in cookie , you can specify that here as well. The default priority is function then the cookie, from where the module will try to fetch data. Note: cookie approach will only work if the Identity Hub is hosted on publisher's domain otherwise accessing first party cookie is not possible.	_fpCookie

Sample first-party function:

To provide first-party data - you can simply expose the function on page with the same name as defined under Function Name.

<script type= "text/javascript" >
     window.getFirstPartyData = function(){
     return   "#hashed-user-identifier" ;
};
</script>

This data will be sent to wrapper consumer and exchanges under key/source firstpartyid. For example:

firstpartyid: "#hashed-user-identifier"

Previous Enabling Lotame Panorama ID™ via Amazon Publisher Services Connections Marketplace (CxM) Next How to Implement the Lotame User ID Module in Magnite