OpenWrap Integration Guide

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

Overview

This documentation describes the process to integrate PubMatic Wrapper tag in a web page of a mobile site once it has been generated. A separate document is available that describes the process/UI for generating a wrapper tag.

 

Introduction

Publishers typically set lower priorities for programmatic demand in their ad servers, thus limiting it to remnant impressions via trafficked tags. The programmatic marketplace can only propose bids for that limited volume of inventory it's exposed to -- and as a result, publishers lose visibility and monetization of high-value programmatic demand on a large share of their traffic.

 

The Wrapper Solution allows publishers to evaluate programmatic bids from multiple sources concurrently for every impression. This also allows ad servers to begin utilizing real-time bids returned instead of the static bids that are used in case of yield tags.

 

How Does Wrapper Solution Work?

The Wrapper Solution provides the pricing from programmatic open marketplaces from multiple SSP partners, which can be consumed by passing key-value pairs to ad servers in real time.

 

An easy-to-use UI provides the option of controlling partners and inventory mapping allowing for quick application and testing.

 

Implementing the Wrapper Solution requires the following steps:

 

Step 1: Create and configure wrapper profile through PubMatic UI. You will get a wrapper tag at the end of this process.

Step 2: Add wrapper tag (JavaScript) to the web page or mobile website.

Step 3: Set up the corresponding line items in the ad server, with settings that allow for consumption of real-time bids at a granular level.

 

Ad Call Flow

  1. PubMatic's Wrapper tag JavaScript code is placed on the publisher site, which makes an ad call to all the configured partners before calling the ad server.
  2. Wrapper solution runs an auction across all the bids from all partners. This happens in the client browser in the JS environment.
  3. Winning bid is sent to the publisher's ad server by dynamically adding this as a key value to the ad server call. PubMatic Wrapper line items are created in the publisher's ad server at various priorities targeting the bid signal in DFP call. The relevant line item is activated.
  4. Publisher's ad server makes the final decision on which campaign/line item to serve considering Wrapper bid as an additional parameter, and the ad is served. 

 

Integration Stages

 Use the following guidelines for the Wrapper Solution integration.

                                 

Activity

ActorDetails
Inventory SetupPublisher Ad Operations
  1. Contact each header tag vendor you're working with to obtain the publisher id/equivalent.
  2. Use OpenWrap to create a profile and configure partners.
  3. Download the Mapping file for each partner and complete. Each partner must create ad tag ids/equivalent and add them to the mapping file.
Configure WrapperPublisher Ad Operations
  1. Upload the completed mapping file.
  2. Complete setup and generate draft tag.
  3. Push to staging when ready to test.
On-page Setup & Integration TestingPublisher Engineering/IT
  1. Copy the wrapper tag to a test web page.
  2. Ensure requests/responses are generated for each header tag the partner included.
  3. At this stage you can set up line items in ad server to capture winning responses. Initially the line items should have broad ‘rates’ so that 2-3 manually created line items serve the testing purpose.
  4. Verify that key/value pairs are passed to the ad server call.
  5. Verify that ad server is responding with the winning ‘creative’ and that the creative is rendered.
Ramp-up Preparation & Testing

Publisher Engineering/IT

 

PubMatic Solutions Engineer

  1. Publisher should provide go ahead to PubMatic solutions engineer to set up granular line items with small increments.
  2. Once line items are created, the publisher should repeat testing to ensure that the correct line items are invoked in response to the relevant bids.
  3. Once verified, the publisher should send test traffic of 100k impressions per day from a live web page.
  4. Perform discrepancy checks between OpenWrap analytics and ad server data.
  5. Discrepancy should be below 20% per the ad server standard.
Go LivePublisher 

On-Page Integration

This section provides implementation instructions for the Wrapper Solution JavaScript.

 

Placing the Wrapper Tag on the Page

 

The following section is applicable only for DFP GPT implementation.

Only Asynchronous GPT tags are supported. For this option, you do not need to develop any additional code for consuming the bid prices.

PubMatic Wrapper script can be loaded Synchronously or Asynchronously.

 

Synchronous Script Tag Example 

<script type="text/javascript">
(function() {
     var purl = window.location.href;
     var url = '//ads.pubmatic.com/AdServer/js/pwt/9999/1';
     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];
          }
     }
     window.document.write('<script type="text/javascript" src="'+url+profileVersionId+'/pwt.js'+'"></scr'+'ipt>');
})();
</script>

 

Asynchronous Script Tag Example

<script type="text/javascript">
(function() {
     var purl = window.location.href;
     var url = '//haso.pubmatic.com/AdServer/js/pwt/9999/109';
     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>

 

Note: All the ad-calls for PubMatic Wrapper implementations are asynchronous. The option for asynchronous and synchronous script determines how the wrapper JavaScript library is loaded.

In order for the Wrapper tag to read GPT slots and intercept DFP calls and inject bid values automatically, it is mandatory that pwt.js is loaded before gpt.js. Otherwise PubMatic wrapper code will not start execution and will remain redundant on the page.

    

 

How can you load pwt.js before gpt.js?

 

When loading pwt.js synchronously

Place the script above the gpt.js call. Since the wrapper library will load synchronously, placing the script above the call will accomplish this.  

 

Example:

<script type="text/javascript">
(function() {
    var purl = window.location.href;
    var url = '//ads.pubmatic.com/AdServer/js/pwt/9999/1;
    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];
        }
    }
    window.document.write('<script type="text/javascript" src="'+url+profileVersionId+'/pwt.js'+'"></scr'+'ipt>');
})();
</script>
<!-- Load GPT library after wrapper script-->
<script async="async" src="//www.googletagservices.com/tag/js/gpt.js">

When loading pwt.js asynchronously 

This is not as straightforward as the synchronous method, as placement of the script doesn't ensure the sequence of loading. Use one of the following options to achieve this:

 

Option A (Preferred Method)

Use a callback to ensure gpt.js is loaded after pwt.js is loaded after pwt.js. 

 

Example: 

<script type="text/javascript">
var PWT={}; //Initialize Namespace
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];
PWT.jsLoaded = function(){ //PubMatic pwt.js on load callback is used to load GPT
    (function() {
        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);
    })();
};
(function() {
    var purl = window.location.href;
    var url = '//ads.pubmatic.com/AdServer/js/pwt/9999/1';
    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>

 

Option B: Configure the same in your tag management solution.

 

The PubMatic Wrapper Tag  is a JavaScript code, which loads as "pwt.js." This JavaScript reads ad unit names and includes a PubMatic publisher ID while querying PubMatic. Similarly, it uses other relevant ids when calling other SSPs for a bid for ad units.

 

 

You will need to place the exact same wrapper code as generated through the UI. The above code is a sample script generated for a demo publisher profile. Wrapper tag should be deployed in the head section of your HTML page before the GPT code.

 

The script will:

  • Define the slots based on the GPT ad units.
  • Make the call to PubMatic and other included header bidding partners for bids.
  • Add winning bid and other information as targeting to GPT call utilizing key/value pairs.

 

Wrapper Partner JS Inclusions and Parameters

Use the information in the tables provided in the Partner JS Inclusions and Parameters document.

 

PubMatic Header Tag

Use the information provided in the PubMatic Decision Manager Standard and Decision Manager Premium API Guides for details.

 

Integration Testing

Complete the following steps to ensure that each header tag in the Wrapper is working successfully:

  1. All the calls for partners are firing for the included/mapped ad units.
  • This can be verified in the network panel of browser console. An ad call should be made to the respective partner end point listed in previous section.
  1. All partners are bidding.
  • This can be verified on the debug console. The debug console is automatically loaded when debugging a version using the debug URL generated while in push to staging mode.

 

Example with a demo page:

  • If a partner is not bidding after multiple tries over a period of several minutes, you may have to take this up with the respective partner.
  1. Winning keys are passed to the ad server.
  • The winning partner can be checked in the debug console. However, to check if the key values are being passed to the ad server you can use the browser console.
  1. Winning creative rendering for each partner.
  • Once any partner wins and the key values are sent to DFP, DFP should deliver the Wrapper tag campaign (which was already configured).
  • If a partner is not winning because of low bids, the publisher can increase the rev-share parameter of other partners in order to make that particular partner win.
  • After rendering the creative, last step is to check that the partner's tracker is fired.
  1. Reporting - Please ensure partners are counting impressions in their system.
  2. Check wrapper analytics. 

 

Ad Server Configuration

Note: If using SafeFrames, see SafeFrames section below.

Refer to instructions provided in the Ad Server Configuration document.

 

Biddable IO and PMP Support

Please refer to Biddable IO documentation to understand how PubMatic supports PMP and PMP-G. 

 

SafeFrames

Publishers using PubMatic’s OpenWrap can place the creative script in a Friendly iframe or a SafeFrame. Using a Friendly iframe, the content from the ad server is rendered into a frame that is on the same server as the host content. SafeFrame is a managed API-enabled iframe that opens a line of communication between the publisher page content and the iframe-contained external contend (e.g., ads). This allows for a line of communication that affords data collection and rich interaction (e.g., ad expansion), that is unavailable in a standard iframe.

 

Creating SafeFrame Line Items in DFP

 

    1. Navigate to the Creative Settings for a line item and enter the appropriate creative script. 

      NOTE: There are different methods for rendering creatives for PMP bids and Open Market bids. Use the appropriate related script below

              




SafeFrame for Rendering PMP Bids

<script src="//ads.pubmatic.com/AdServer/js/pwt/%%PATTERN:pwtpubid%%/%%PATTERN:pwtprofid%%/%%PATTERN:pwtverid%%/pwt.js">
</script>
     
<script type='text/javascript'>
      (function() {
            try {
                 window.PWT.sfDisplayPMPCreative(document, '%%PATTERN:pwtdeal_pubmatic%%', []);
} catch (e) {}
      })();
</script>

 

 

SafeFrame for Rendering Open Auction Bids

 

<script src="//ads.pubmatic.com/AdServer/js/pwt/%%PATTERN:pwtpubid%%/%%PATTERN:pwtprofid%%/%%PATTERN:pwtverid%%/pwt.js">
</script>

<script type='text/javascript'>
    (function() {
        try {
            window.PWT.sfDisplayCreative(document, '%%PATTERN:pwtsid%%');
        } catch (e) {}
    })();
</script>
     

2. Select the checkbox for Serve into a SafeFrame.

3. Complete any other fields required and click Save.

Safe Frame Scenario and Results

Scenario

Result

Inside DFP, safe frame creative code added but safe frame option is not selected.

Creative rendered correctly if it does not use safe frame feature. For example, a static image creative renders correctly but an expandable creative that relies on safe frame will not work correctly.

Inside DFP, legacy/regular pwt creative code added, safe frame option selected and safe frame creative rendered.

Error seen on browser console. Creative is rendered but if it is rich media creative/expandable then it will not work as expected.

Display non-compatible expandable creative inside safe frame

Creative does not render correctly or post creative expansion results into page error or unknown behavior.

Display safe frame creative inside a non-safe frame  

Error seen on the browser console. Creative is rendered but if it is rich media creative/expandable then it will not work as expected.

Important Note: Creative to be rendered inside safe frame must be safe frame compatible and needs to be tested on the page.

References

To learn more about SafeFrames, refer to:

 

Known Limitations

Post-timeout bids

  • Prebid does not share the bids received from partners after timeout. As a result, we cannot log information about the post-timeout bids such as latency and ecpm and there won't be any bids with a "t" parameter set to 1 in our Openwrap analytics.
  • Currently, the default bid (db) flag will be set only if partner endpoint gives an error (internal server error, not found, etc.) or times out (t will not be set to 1).
  • Modifications to Prebid code to support logging post-timeout bids are pending and are not part of this release.

 

Code Generation Performance

Below is the performance of code generation with gulp execution through the API with varying the number of adapter partners.

Number of PartnersTime to Execute
118-20 seconds
1025-30 seconds

   

This has an impact on flow, user flows and API calls:

  • Copying profile
  • Push wrapper code to staging
  • Mapping upload


Safe Frame

Expandable creative will not work correctly after rendering inside of a safe frame on Safari, IE11/Edge.

 

Support for Previous Code Build

When a stable code build of OpenWrap (with Prebid) is released, we will not support prior code builds. All subsequent OpenWrap profile versions will use the new stable code build.

 

Rubicon Legacy Adapter Support

OpenWrap will not support Rubicon legacy adapter in any future code builds.

 

Rubicon Legacy adapter will work only with older code build (release prior to OpenWrap with Prebid).

NOTE: To use Rubicon Fastlane, the publisher must migrate the account from Rubicon to Rubicon Fastlane and get new IDs to map in OpenWrap.

 

Advanced GPT

Advanced GPT implementations are not supported, as a result of a known bug in Prebid (https://github.com/prebid/Prebid.js/issues/914). We will be releasing a new nightly code base that will address this issue.

We recommend not using the first nightly code build for publisher running advanced GPT implementation on their pages.

Attachments

    Outcomes