OpenWrap User Guide

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

OpenWrap Solution Overview

OpenWrap simplifies the header tag integration process and post-integration management for publishers. By passing the necessary controls to publishers’ ad/business operations teams, OpenWrap improves publishers’ ability to maximize monetization opportunities.

 

This guide provides key features and functions of OpenWrap as well as instructions to use configurable controls and generate wrapper tags.

 

Glossary of Terms

Partners = SSP/Exchanges whose header tag is included in the wrapper.

Profile = Defines inventory for the wrapper. Includes configuration settings for the OpenWrap. 

Version = A version of a profile. Refers to the settings included in the profile. One profile can include multiple versions (only one can be the live version in production). 

Wrapper Tag = JavaScript (JS) code that includes multiple header tags, in addition to configuration, management and analytics code. 

 

OpenWrap Key Features and Functions

PubMatic OpenWrap:

  • is an extension to Prebid open source code.
  • contains multiple underlying header tags. The wrapper tag ensures that header tags can run concurrently.
  • auto-detects ad units on a page. OpenWrap collects the necessary identifiers such as unit name, div ID and size, and uses those to send partner-specific identifiers.
    Example: PubMatic requires ad unit name and ad size to identify the ad opportunity. This removes the burden on your engineering team to collect, map and maintain all the ad unit identification data on a partner-by-partner basis for every page.
  • provides an ad unit to partner-specific identifier mapping interface.
  • offers the ability to configure controls such as traffic allocation, bid adjustment, and timeout values.
  • handles decisioning on page and passes the partner’s information and the winning bid to the Ad server.
  • creates line items in the publishers’ ad server.
  • delivers critical insights with analytics. Analytics include volume-related metrics, monetization-related metrics and latency-related metrics.

 

Publisher Requirements 

The following are requirements for using PubMatic OpenWrap:

  1. Ensure that you have access to web pages that would include the wrapper.
  2. Define inventory groups of less than 500 ad units per group. Each group of inventory should be configured in a separate profile.
  3. Ad Unit Mapping
  • Identify all ad units with ad unit names, div IDs, and ad size. This information should be entered in the mapping file format for each partner. This file format is available in the PubMatic Wrapper Profile Management tab.
  • Register those ad units with each partner you want to work with, and get a unique ID from each partner. For example, provide ad unit name + size to your PubMatic contact and in return receive corresponding site id and ad tag id.
  • Inspect the contents of the file to make sure that the file is duly completed.

  1. Access to Ad server: Provide trafficker level access to the PubMatic team to assist with creating line items in ad server.

 

Getting Started

Use the instructions in this section to configure OpenWrap.

 

Log in and Navigate to OpenWrap

      1. Open http://www.pubmatic.com/.

      2. Click Login | Publishers.

      3. Enter login credentials and click Login.

      4. Select Inventory & Rules | Wrapper Tags.

Wrapper Tag Configuration Tabs

      • Partner Management: Add a new partner. 
      • Profile Management: Create a new profile or manage an existing profile. 
      • Tag Management: Retrieve wrapper tags for a selected profile.

 

Adding a Partner

Before you can edit profiles and generate tags for partners, you must first add them in the Partner Management tab. PubMatic OpenWrap supports the following partners. (For the most current list of partners, refer to the partner selection list in the PubMatic platform when adding a partner.)

  • PubMatic (automatically added)
  • AdForm
  • AOL
  • AppNexus
  • bRealtime
  • DistrictM
  • Index
  • PulsePoint
  • Rubicon
  • Sovrn

 

Partners are added to OpenWrap using the same method. However, each partner may require different inputs. Refer to the table below for partner-specific inputs.

 

To Add a Partner

      1. From the Partner Management tab, click Add Partner.
      2. Select a partner from the Partner drop-down menu.
      3. Enter an Account Name (Use a naming convention that will help you identify the partner account, particularly if you have multiple accounts with a partner.)
      4. Use the guidelines below to add appropriate information for each partner. This information should be received from the respective partner.

        PartnerRequired Information
        AdFormAccount Name (alias)
        AdForm Domain
        AOL

        Account Name (alias)

        Network ID

        Server Domain

        AppNexusAccount Name (alias)
        bRealTimeAccount Name (alias)
        DistrictMAccount Name (alias)
        Index ExchangeAccount Name (alias)
        PulsePoint

        Account Name (alias)

        Publisher ID

        Rubicon Fastlane

        Account Name (alias)

        Account ID

        SovrnAccount Name (alias)
      5. Click Save.

 

Profile Management

A Profile defines groups of inventory that will have the same configuration settings. Profiles are managed from the Profile Management Tab. To learn more about managing profiles, refer to the Profile Management guide.

 

Post-Integration Configuration Changes

OpenWrap makes it easy to change many settings, including:

  • Adding or removing a partner from a Profile
  • Update Mapping
  • Throttling traffic to an existing partner
  • Updating Bid Adjustment share amount
  • Changing time out settings

To Add a New Configuration

  1. Select the Profile Management tab.
  2. Click on a profile to select it.
  3. Select Actions | Create New Version next to the most recent version.
  4. Make changes to the Traffic Allocation, Bid Adjustment and Timeout (ms).

Note: Index Exchange responds with currency in their header bidding response. Be sure to clarify which currency Index Exchange will respond with for your specific set up and enter a suitable value in the Bid Adjustment field to account for currency conversion so that all responses can be compared in USD.

 

Please note that OpenWrap does not carry out any further currency conversions, and only takes bid adjustment field into account for these adjustments.

      

  1. Add or remove partners if required by clicking on the dropdown under Select Partners as shown below.

    Once all settings are finalized, and mappings completed in a similar way as explained earlier in this guide -- the newly created version will be in DRAFT state.
  2. To start testing the next version, push the version to staging by selecting Push to Staging. The ‘Status’ of the version will update to STAGING.

    This process may take 15-30 seconds.

          

    Do not select Push to Production until the new version has been tested. In order to test, select Actions | Debug URL, to append to your page URL where the new version is expected to run.


    Debug URL looks like this: ‘?pwtv=1&pwtvc=1’’.


    As an example publisher who is running version 1 on yourdomain.com, would test Version 2 using this URL ‘yourdomain.com/ ?pwtv=1&pwtvc=1’.

  3. Once testing in complete, select Actions | Push to Production.

    This will swap the active version (previous production version) to a new version. No on-page changes are required when a new version is created for the same profile.

    IMPORTANT:

    For any given profile, only one version can be the active version running in production.

    It may take 5-10 minutes to CDN flush to reflect the changes.

    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.

       

      Limitations

      • As creative will render in safe frame, partner creative might report URL mismatch in data gathered while creative rendering
      • Any creative taking benefit of friendly frames will not be able to do so in safe frame
      • Partners would not know in advance that the creative will render in safe frame, there has to be a way we can inform partner about it (partner needs input param)
      • We will try to render creative by creating FF in SF. We will use synchronous rendering if rendering creative in an FF fails in SF, this happens in IE and Safari. When we use synchronous rendering in SF, any creative taking advantage of SafeFrame will not work.

       

      References

      To learn more about SafeFrames, refer to:

       

      OpenWrap Analytics

      There are two types of reports available in PubUI.

       

      1. Daily Scheduled Reports in PubUI:

       

      This report is available in dashboard. Report is in the excel format and contains the following dimensions and metrics:

      • Publisher id
      • Date
      • Partner id
      • Ad Unit id
      • Profile id
      • Profile display id
      • Ad size
      • Request count
      • Response count
      • Monetized impression count
      • Timeout Count
      • Bid CPM
      • Monetized CPM
      • Average Latency
      • Bid Adjustment

       

      About Bid Response Latency

      OpenWrap provides the bid response latency.

          • This includes the execution of the partner ad-client script, network call for bid, JS execution post bid response for parsing and appending to DFP. Due to these factors, the average latency will always be higher than the network call time that may be seen/measured using console or firebug plugin.
             
          • Creatives load with their own latency, meaning, the time that it takes for the winning bidder to provide creatives and load them on the browser, at which point it becomes visible to the user. OpenWrap currently does not measure that time. For some SSP/exchanges this time may be high, and the publisher should work with the originating exchange to provide any related feedback.

       

      2. Standard Reports Available in Analytics:

       

      Currently there are two reports available in Analytics. You can access these two reports PubMatic | Analytics | Reports | Standard Reports.

       

      1. Wrapper Revenue Report, which includes:
        Date
        Partner
        Profile
        Revenue
        Requests
        Responses
        Monetized Impressions

      2. Wrapper Bid Activity Report, which includes:
        Date
        Partner
        Profile
        Revenue
        Requests
        Responses
        Bid eCPM
        Monetized eCPM
        Bid Rate
        Win Rate
        Fill Rate 

      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