OpenWrap Integration Guide

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Apr 20, 2018
Version 16Show Document
  • View in full screen mode

This documentation describes the process of integrating the wrapper tag in OpenWrap. For more information about generating a wrapper tag refer to the OpenWrap User Guide

 

Why Use OpenWrap?

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. As a result, publishers lose visibility and monetization of high-value programmatic demand on a large share of their traffic.

 

OpenWrap provides a transparent enterprise wrapper solution for Prebid and lets publishers evaluate programmatic bids from multiple sources concurrently for every impression. OpenWrap also lets ad servers begin utilizing real-time bids returned instead of the static bids that are used in case of yield tags.

 

How Does OpenWrap Work?

OpenWrap 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.

 

To implement OpenWrap:

 

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's site, which makes an ad call to all the configured partners before calling the ad server.
  2. OpenWrap runs an auction across all the bids from all partners.
  3. The 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 OpenWrap 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 OpenWrap 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 OpenWrap 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>
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?

You can load pwt.js before gpt.js either synchronously or asynchronously. See the following sections for details on each approach.

 

Synchronously Loading pwt.js

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">

 

Asynchronously Loading pwt.js

This is not as straightforward as the synchronous method, as placement of the script doesn't ensure the sequence of loading. See the following sections for your options to asynchronously load pwt.js.

 

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 must 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.

 

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.
  2. 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.
  3. 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.
  4. 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.
  5. Reporting - Please ensure partners are counting impressions in their system.
  6. Check wrapper analytics. 

 

Ad Server Configuration

If using SafeFrames, see SafeFrames.

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. 

    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.

 

SafeFrame Scenario and Results

Scenario

Result

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

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

Inside DFP, legacy/regular pwt creative code added, safeframe option selected and safeframe 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 safeframe

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

Display safeframe creative inside a non-safeframe  

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

Creative to be rendered inside safeframe must be safeframe compatible and needs to be tested on the page.

References

To learn more about SafeFrames see:

 

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

 

SafeFrame

Expandable creative will not work correctly after rendering inside of a safeframe 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 builds (releases prior to OpenWrap with Prebid).

To use Rubicon Fastlane, publishers must migrate their accounts from Rubicon to Rubicon Fastlane and get new IDs to map in OpenWrap.

 

⇧ Top

Attachments

    Outcomes