V3 PubWise Integration

What’s New In V3

PubWise Tag Code: The PubWise on-page Tag Code is the primary difference. This method improves performance, configurability and maintainability.

Lazy Load and Refresh: Lazy load and refresh are handled in the backend. They are no longer Adunit variables.

Dynamic Adunit Bidding: The dynamic adunits no longer use a variable to indicate their status. Instead they use a “template” method by passing in a second parameter. This simplifies configuration and is easier to explain, understand and implement.

V2 & V3 Can Coexist: V3 Integration PubWise Adunits can coexist on the page with V2 adunits. You can transition to new functionality one adunit at a time if desired.

Standard Integration Summary

The PubWise integration consists of these primary actions:

  1. Add PubWise Script
  2. Modify Google Ad Manager Tag Code
  3. Add PubWise Tag Code
  4. PubWise Configures Prebid Bidding

Standard Integration Details

Add PubWise Script

The scripts for your site are custom URLs only for your site. They are provided by your Customer Success Manager.

Modify Google Ad Manager Tag Code

Standard GAM Tag Code 

googletag.cmd.push(function() {
  googletag.defineSlot('/dfpAdUnit', 'div-1').addService(googletag.pubads());
  googletag.defineSlot('/dfpAdUnit2', 'div-2').addService(googletag.pubads());
  // other GAM code
});

Modification Required

The update GAM Tag Code requires a variable named “gptadslots” which contains the GAM Adunits indexed by the DIV IV. This is done like the following:

var gptadslots = [];
googletag.cmd.push(function() {
  gptadslots['div-1'] = googletag.defineSlot('/dfpAdUnit', 'div-1').addService(googletag.pubads());
  gptadslots['div-2'] = googletag.defineSlot('/dfpAdUnit2', 'div-2').addService(googletag.pubads());
  // other GAM code
});

Add PubWise Tag Code 

<div id='div-1' style="min-height:90px;">
  <script type='text/javascript'>
    pubwise.que.push(function() {
      pubwise.renderAd('div-1');
    });
  </script>
</div>

PubWise Configures Prebid Bidding

Your Customer Success Manager will configure all entries in the gptadslots variable for Prebid bidding.

Adhesion

Adhesion adunits which attach to the bottom of the screen can be added via script config. For Fully Managed customers this is handled by your account manager.

In certain cases you may want to interact with the adhesion divs and behavior to load your own elements in the page. The below sections document how to do this.

Adhesion Events & Status

The adhesion adunit loads certain divs and emits events and statuses. The below events and statuses should be evaluated inside the PubWise queue like the below.

pubwise.que.push(function() {
   // evaluate events and status
}

Event List

  • Event: PUBWISE_ADHESION_READY
    • emitted after the adhesion loads
  • Ready Status: pubwise.status.PUBWISE_ADHESION_READY
    • starts at false and turned to true after the PUBWISE_ADHESION_READY event is fired
  • Active Status: pubwise.dyn_adunit_config[0].active
    • indicates whether any adhesion code is active on the page

Active

The following variable will be 0 if no adhesion adunit is configured and 1 if it is. If the adhesion is not active then no divs will be created. In the 0 case the page can be treated as if no adhesion exists.

pubwise.dyn_adunit_config[0].active == 1

PUBWISE_ADHESION_READY Status

The following variable will be set after the adhesion event fires. This allows for detection of the event firing before your code runs. If pubwise.status.PUBWISE_ADHESION_READY is true then the event has already fired and you can continue with code that interacts with the adhesion divs.

pubwise.status.PUBWISE_ADHESION_READY

PUBWISE_ADHESION_READY Event

This JavaScript event is fired on the document.body when the adhesion loads. The pubwise.status.PUBWISE_ADHESION_READY status variable is also set to true at this time.

Div Created by Adhesion

The following divs are created as a position fixed div. Customer custom contents should be added BEFORE the pw-adh-dyn div and INTO the pw-adh-dyn-container.

<script>
var containerEl = document.createElement(\'div\');
containerEl.id = \'pw-adh-dyn-container\';
        containerEl.setAttribute(\'style\',\'position:fixed;bottom:0px;left:0px;z-index:99999;margin:0px;padding:0px;width:100%;min-height:0px;padding:0px 0;text-align:center;\')

var newEl = document.createElement(\'div\');
newEl.id = \'pw-adh-dyn\';
newEl.setAttribute(\'style\',\'background-color:\'+pubwise.dyn_adunit_config[0].color_background+\';margin:0px;padding:0px;width:100%;min-height:0px;padding:0px 0;text-align:center;\')
</script>

Sample code to interact with the above…

<script>
var diffEl = document.createElement('div');
diffEl.id = 'another-diff-div';
diffEl.setAttribute('style','border:2px solid; border-color:#ff33ff;height:50px;width:300px;margin:0 auto;margin-bottom:10px;padding-right:5px;');


document.getElementById('pw-adh-dyn-container').insertBefore(diffEl,document.getElementById('pw-adh-dyn'));
</script>

Sample Logic Flow 

pubwise.que.push(function() {
    function loadIntoAdhesion(event) {
      // your customer custom code for loading WITH adhesion
    }
    function loadWithoutAdhesion() {
      // your customer custom code for loading WITHOUT adhesion
    }

   if (pubwise.dyn_adunit_config[0].active == 0) {
      // do customer loading as if no adhesion divs exist
      loadWithoutAdhesion()
   }else{
      // perform customer loading using the adhesion divs
      if (pubwise.status.PUBWISE_ADHESION_READY == true) {
        // the PUBWISE_ADHESION_READY event has already fired
        // perform customer loading using the adhesion divs
        loadIntoAdhesion();
      }else{
        document.addEventListener("PUBWISE_ADHESION_READY", loadIntoAdhesion);
      }
    }  
}

Additional Integration Options

We support a variety of additional integrations including Single Page Apps, Mobile, Lazy Load, Viewable Refresh, Sliders, Adhesions & more. The vast majority of integrations are handled by the following code examples. Your Customer Success Manager can assist with custom documentation for any special integration.

Lazy Load

Talk to your Customer Success Manager to enable lazy load. This is handled in the backend script and fully supported with the standard integration.

Refresh & Viewable Refresh

Talk to your Customer Success Manager to enable refresh and viewable refresh. This is handled in the backend script and fully supported with the standard integration.

Dynamic AdUnits

In the case of dynamic adunits the GAM Adunit in the GAM Tag Code does not exist when the page initially loads. To account for this, create the GAM Adunit dynamically, add it to the GPTAdSlots, and then call the PubWise Tag Code render function with a reference to a gptadslots entry that did exist in the intial load. The provided second GAM Adunit must exist in the initial config and will be used as a template for Prebid to bid on the new dynamically created GAM Adunit. The second paramater is optional but it is valid to pass the same value in again.

Speak with your Customer Success Manager to coordinate ensuring the initial adunit is configured properly and available. We’re available, and happy to verify integration code to ensure success.

First Ad Unit

In the head…

<head>
var gptadslots = [];
googletag.cmd.push(function() {
  gptadslots['div-1'] = googletag.defineSlot('/dfpAdUnit', 'div-1').addService(googletag.pubads());
  gptadslots['div-2'] = googletag.defineSlot('/dfpAdUnit2', 'div-2').addService(googletag.pubads());
  // other GAM Tag Code
});
</head>

In the page…

<div id='div-1' style="min-height:90px;">
  <script type='text/javascript'>
    pubwise.que.push(function() {
      pubwise.renderAd('div-1', 'div-1');
    });
  </script>
</div>

The dynamic adunit later in the page or after user interaction, etc….

<script>
googletag.cmd.push(function() {
  gptadslots['div-dynamic'] = googletag.defineSlot('/GAMAdunit', 'div-dynamic').addService(googletag.pubads());
});	
</script>
<div id='div-dynamic' style="min-height:90px;">
  <script type='text/javascript'>
    pubwise.que.push(function() {
      pubwise.renderAd('div-dynamic', 'div-1');
    });
  </script>
</div>

Protecting Ad Loads

In certain cases PubWise is not active on the page or you wish to disable the integration temporarily. To reduce code changes in this case we recommend integrating ad units on the page like the following.

<div id='div-1' style="min-height:90px;">
  <script type='text/javascript'>      		  			       
    if (typeof(pubwise) != 'undefined' && pubwise.enabled === true) {
      pubwise.que.push(function() {              
          pubwise.renderAd('div-1');
      });
    }else{
      googletag.cmd.push(function () {                    
        googletag.display('div-1');
        googletag.pubads().refresh([gptadslots['div-1']]);          				
      });
    }
  </script>
</div>

Loading Without pre_pws.js

Header Bidding code has an intimate, but separate, relationship with the in-page GAM/GPT code. The pre_pws.js provides certain convenience capabilities by being loaded synchronously. It sets up GAM/GPT to disableIintialLoad docs while also providing a hook to disable the PubWise script from the UI while concurrently removing the disableInitialLoad. Loading the script asynchronously handles all of this without introducing race conditions. It is possible to load withtout the pre_pws.js script if certain variables and setup are done directly in the page. This does have tradeoffs and those tradeoffs are listed below:

Benefits of Removing pre_pws.js

  1. Slight performance improvement
  2. Improved control in frameworks that dynamically load PubWise scripts like SPAs and similar

Cons of Removing pre_pws.js

  1. The addition and removal of the GPT disableInitialLoad call is no longer tied to the load status of PubWise. Customers may require a code deployment to reenable initial load if they are not otherwise detecting the load status of PubWise.
  2. Overall this integration is more custom and the code deployment requirements involve more customer page level code.

How to Remove the pre_pws.js Script

The following variables and code need to be present in the page before loading any ads and before making any GPT related code calls. We suggest doing this just after the simliar variables that GPT requires which we call “Existing GPT Code” below. Fundamentally, the key element is that these variables and queues are in scope before Ad Manager and GPT do any work and before the primary PubWise script is loaded.

Existing GTP Code

<script>
  var gptadslots=[];
  var googletag = googletag || {};
  googletag.cmd = googletag.cmd || [];
</script>

PubWise Code

<script>
  googletag.cmd.push(function() { googletag.pubads().disableInitialLoad(); });
  var pbjs = pbjs || {};
  pbjs.que = pbjs.que || [];
  var pubwise = pubwise || {};
  pubwise.cmd = pubwise.cmd || [];
  pubwise.que = pubwise.que || [];
  pubwise.observers = pubwise.observers || [];
  pubwise.adconfig = pubwise.adconfig || [];
  pubwise.enabled = true;
</script>