PubCID for Publishers

Prebid User ID Module

How to Integrate

Download the Prebid User ID module, including the optional "User ID" module. Alternatively, you can build Prebid from source and include the following command to utilize the "User ID" module:

 

gulp build –modules=userId,pubCommonIdSystem

 

Conversant also recommends implementing a method where users can easily opt-out of targeted advertising. Please refer to the User Opt-Out section located at the bottom of this page.

Configuration

By including the User Id module, the following options become available in setConfig(), all of them under the usersync object as attributes of the userIds array of sub-objects. 

Param Under usersync.userIds[] Scope Type Description Example
name Required String Must be: "pubCommonId" "pubCommonId"
storage 

Required (unless value is specified)

Object The publisher must specify some kind of local storage in which to store the results of the call to get the user ID. This can be either cookie or HTML5 storage.  
storage.type Required String This is where the results of the user ID will be stored. Must be either: "cookie" or "html5" "cookie"
storage.name Required String The name of the cookie or html5 local storage where the user ID will be stored. "_pubcid"
storage.expires Optional Integer How long the user ID information will be stored. Default is 1,825 days for PubCommonID. 365


Conversant PubCID Script

How to Integrate

This integration option is best suited for Conversant Ad Code and custom integrations which don't leverage Prebid.

  1. Clone the Conversant PubCID script repository 
  2. Implement the pubcid.js script on the desired page by following the build instructions in the readme.md
Conversant also recommends implementing a method where users can easily opt-out of targeted advertising. Please refer to the User Opt-Out section located at the bottom of this page.

Configuration

If there are no custom configurations, then just include the script and it'll use the default values.

<script type="text/javascript" src="//myserver.com/pubcid.min.js"></script>


If custom configurations are needed, define the pubcid_options object before inclusion of the script. Below is an example to switch from using local storage to cookie:

<script type="text/javascript">
   window.pubcid_options = {type: 'cookie'};
</script>
<script type="text/javascript" src="//myserver.com/pubcid.min.js"></script>

 

List of Options

Parameter Name Type Description Example
expInterval decimal Expiration interval in minutes. Default is 525600, or 1 year 525600
type  string Type of storage. It's possible to specify one of the following: 'html5', 'cookie'. Default is 'html5' priority, aka local storage, and fall back to cookie if local storage is unavailable. 'cookie'
create  boolean If true, then an id is created automatically by the script if it's missing. Default is true. If your server has a component that generates the id instead, then this should be set to false true
extend  boolean If true, the the expiration time is automatically extended whenever the script is executed even if the id exists already. Default is true. If false, then the id expires from the time it was initially created. true
pixelUrl  string This is the only needed there is a server component, which has a special end-point that creates/extends the id as a cookie. It's not useful when local storage is used. /wp-json/pubcid/v1/extend/


Sample Configurations

Always use cookies and create an ID that expires in 30 days after creation.

{ 
    type: 'cookie',
    extend: false,
    expInterval: 43200
}


Server-Side Cookie

The configuration options only control the behaviors on the Javascript side, while the server-side has its own configuration that's done separately. Both sets need to coordinate with each other.
The script creates the cookie, but leaves it to the server-side to extend the cookie. No special endpoint is needed because the server checks all pages.

{ 
    type: 'cookie'
}

Script creates the cookie and the server extends expiration through an endpoint.

{ 
    type: 'cookie',
    pixelUrl: '/wp-json/pubcid/v1/extend/
}

Server creates the cookie once, which will expire before it is created again.

{ 
    type: 'cookie',
    pixelUrl: '/wp-json/pubcid/v1/extend/',
    create: false,
    extend: false
}

 

User Opt-Out

Conversant recommends implementing a method where users can easily opt-out of targeted advertising. User opt-out is supported by setting the _pubcid cookie in the publisher’s domain. When this cookie is set, then Publisher Common ID is neither read nor updated, and it will not be made available. The opt-out should also delete the Publisher Common ID cookie (shown in example).  Alternatively, setting the same value in local storage will also work. Upon implementation, the user opt-out link should be placed on the Privacy Policy page.

  • Opt-In: _pubcid_optout cookie is not present or set to 0
  • Opt-Out: _pubcid_optout cookie is set to 1
Here is an example of implementing opt-out and opt-in for the Publisher Common Id.

<html>
<head>
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/jquery-confirm/3.3.0/jquery-confirm.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-confirm/3.3.0/jquery-confirm.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
$("#fpcsettings").click(function() {
showDialog();
});
});

function setCookie(name, value, days) {
var d = new Date;
d.setTime(d.getTime() + 24*60*60*1000*days);
document.cookie = name + "=" + value + ";path=/;expires=" + d.toGMTString();
}

function deleteCookie (name){
setCookie(name, '', -1);
}

function showDialog(){
$.confirm({
title: 'Publisher Common ID Opt Out',
content: 'Publisher Common ID Opt Out',
cancelButton: 'Opt Out',
buttons: {
optin:{
text: 'Opt Out',
action: function(){
setCookie('_pubcid_optout', '1', 1825);
deleteCookie('_pubcid');
try {
localStorage.setItem('_pubcid_optout', '1');
localStorage.removeItem('_pubcid');
localStorage.removeItem('_pubcid_exp');
}
catch (e) {
console.log('local storage unavailable');
}
}
}
}
});
}

</script>
</head>
<body>
To control Publisher Common ID settings <a id="fpcsettings">click here</a>.
</body>
</html>