OpenWrap User Guide

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

OpenWrap simplifies header tag integration and post-integration management for publishers. OpenWrap provides a transparent enterprise wrapper solution for Prebid to publishers who want to increase monetization with access to the broadest set of exchanges and unique demand. OpenWrap simplifies partner management with hybrid client-side and sever-to-server management capabilities in an intuitive UI, with enterprise grade analytics and a dedicated team for account optimization and support.

 

This guide describes key features and functions of OpenWrap and step-by-step instructions to use configurable controls and generate wrapper tags.

 

Glossary of Terms

Client-side
The user's web browser (the client) sends ad requests directly to partners. Client-side request processing has the highest user match rate but can slow web page loading.
Partners
SSP/Exchanges whose header tag is included in the wrapper.
Profile
Defines inventory for the wrapper. Includes configuration settings for the OpenWrap.
Server-side
Ad requests go first to an OpenWrap server, which then sends them to partners.  Server-side request processing can speed web page loading but can reduce user match rate compared to client-side processing.
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:

 

  • Provides a transparent enterprise wrapper solution for Prebid with DFP (DoubleClick For Publisher) or UAS (Unified Ad Server) as a publisher ad server.
  • Simplifies partner management with hybrid client-side and server-to-server management capabilities in an intuitive UI with enterprise-grade analytics.
  • 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 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, then 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, monetization-related, and latency-related metrics.

 

Publisher Requirements 

Using PubMatic OpenWrap requires the following:

 

  1. Access to web pages that will include the wrapper.
  2. Define inventory groups of less than 500 ad units per group. Configure each inventory group in a separate profile.
  3. Ad Unit Mapping:
  • Identify all ad units with ad unit names, div IDs, and ad sizes. Enter this information in the mapping file format for each partner (you'll find the file format in the Actions drop-down menu for a specific profile within the OpenWrap Profile Management tab—Learn More…).
  • 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 and 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 it is complete.
  1. Access to Ad server: Provide trafficker level access to the PubMatic team to assist with creating line items in ad server. This is required if publisher ad server is DFP.

 

Getting Started

Use the instructions in this section to configure OpenWrap.

 

Log in and Navigate to OpenWrap

  1. Select Inventory | OpenWrap.

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.

  

 

Add a Partner

Before you can edit profiles and generate tags for partners, you must first add them in the Partner Management tab. The process you use to add partners to OpenWrap is always the same, but each partner may require different inputs. 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* (added automatically)
  • Ad Generation
  • AdForm
  • AOL
  • AppNexus*
  • bRealtime
  • C1Exchange
  • Conversant
  • Criteo
  • DefyMedia
  • DistrictM
  • Facebook Audience Network*
  • Index Exchange*
  • Kargo
  • PulsePoint*
  • Rubicon Fastlane
  • Sekindo Universal Mccann
  • Sovrn
  • TripleLift
 * These partners support server-side OpenWrap.

To Add a Partner

  1. From the Partner Management tab, choose Add Partner.
  2. Select a partner from the Partner drop-down menu.
  3. Enter an Account Name (if you have multiple accounts with a partner, use a naming convention that will help you identify each partner account).
  4. Add the required information for each partner (for example, Account Alias, Domain, Network ID, and so on—obtain this information from your partner if you don't already have it).
  5. Choose Save.

 

Profile Management

Profiles define groups of inventory that use the same configuration settings. Manage your profiles from the Profile Management tab. See OpenWrap Profile Management for details.

If you want to use OpenWrap with AMP pages see, OpenWrap AMP Support.

Post-Integration Configuration Changes

OpenWrap makes it easy to change many settings, including:

 

  • Add or remove a partner from a Profile
  • Update Mapping
  • Throttle traffic to an existing partner
  • Update Bid Adjustment share amount
  • Change time out settings
  • Change whether a partner who supports server-to-server will run client-side or server-side.

 

To Add a New Configuration

  1. Select the Profile Management tab.
  2. Select a profile from the Select Profile drop-down list .
  3. Choose Actions | Create New Version next to the most recent version.

     

    One of two different styles of the Edit Profile dialog will display. Select the link below that matches your Edit Profile dialog:

 

Client-Side Partner Profiles

  1. Make changes to the Traffic Allocation, Bid Adjustment, and Timeout (ms) fields.
    Index Exchange responds with currency in the header bidding response. Be sure to clarify the type of currency Index Exchange uses for your specific set up. Enter a suitable value in the Bid Adjustment field to adjust for currency conversion so that all responses can be compared in USD.

    Also note that OpenWrap does not perform any further currency conversions; the Bid Adjustment field is the only factor used for currency adjustments.

Server-Side Partner Profiles

  1. Make changes to the Traffic Allocation, Bid Adjustment, and Timeout (ms) fields. Additionally, also check the Server Side box for each partner that you want to run server-side. Leave the Server Side box unchecked for any partners that you want to continue to run client-side.
    Index Exchange responds with currency in their header bidding response. Be sure to clarify the type of currency Index Exchange uses for your specific set up and enter a suitable value in the Bid Adjustment field to adjust for currency conversion so that all responses can be compared in USD.

     

    Please note that OpenWrap does not carry out any further currency conversions; the Bid Adjustment field is the only factor used for currency adjustments.


    If all partners in the profile are configured as server-side, make sure at least one of them have timeout more than 500 ms (preferably 100 ms or more) to account for network round trip from user browser to server-side wrapper component. Even if timeout is more than 500, server-side component would cap the timeout for outbound bid request to 500 ms.

Add or Remove Partners

  1. Add or remove partners if required by using the Select Partners drop-down (shown below).



Ad Server

  1. Select AdServer, then choose either DFP or UAS from the list. 

     



Release Version

  1. Select the OpenWrap build version that will generate OpenWrap code for your profile.

    Use the STABLE version if you are not sure of what this is.

    Use NIGHTLY code builds only with the assistance of the PubMatic Ops team.

Send All Bids

  1. Select Send All Bids if you don't want the wrapper to conduct the auction and send bids from all configured partners directly to DFP.
    This feature is available only  with DFP as ad server.
    When you have finalized all settings and have completed mappings as mentioned earlier in this guide, you will have a new DRAFT version.
  1. Enable consent management if this profile is going to get traffic from European regions regulated by  GDPR.
    See OpenWrap Profile Management for more details around all configuration related to consent management.

Testing Your Draft Version

  1. To start testing the next version, push the draft version to staging by selecting Push to Staging. The Status of the version then updates to, STAGING.

    The update 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.

    A debug URL looks like this:

    ?pwtv=1&pwtvc=1

    For example, a publisher who is running version 1 on yourdomain.com, would test Version 2 using this URL:

    yourdomain.com/?pwtv=1&pwtvc=1
  2. Once testing in complete, select Actions | Push to Production. This replaces the active version (previous production version), with the new version.

    No on-page changes are required when you create a new version for the same profile.
    IMPORTANT: Each profile can have only one active version running in production. It may take 5-10 minutes to reflect the change.

Private Marketplace-Guaranteed (PMP-G) Support

Please refer to PMP-Guaranteed Implementation Guide for Publishers to understand how PubMatic supports PMP-G. 

 

SafeFrames (Only for DFP Ad Server in OpenWrap)

Publishers using PubMatic’s OpenWrap have the opportunity to place the creative script in a SafeFrame instead of a standard Friendly iframe. Using a Friendly iframe, the ad server renders the content into an frame on the same server as the host content. But a SafeFrame is a managed, API-enabled iframe that communicates between the publisher page content and the ad rendered in the iframe. This lets SafeFrame collect data and provide rich interaction (such as ad expansion), that is unavailable with 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, Serve into a SafeFrame.
  3. Complete any other fields required, then choose Save.

 

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

Any creative to be rendered inside a SafeFrame must be SafeFrame compatible and must be tested on the page.

Limitations

  • As creative will render in a SafeFrame, partner creative might report URL mismatch in data gathered during creative rendering.
  • Any creative taking benefit of friendly frames will not be able to do so in SafeFrame.
  • Partners may not know in advance that the creative will render in SafeFrame, so the partner must input a parameter to be notified about the SafeFrame.
  • We will try to render creative by creating a friendly frame in a SafeFrame. We will use synchronous rendering in IE and Safari if a friendly frame creative fails in a SafeFrame. When we use synchronous rendering in SafeFrame, any creative taking advantage of SafeFrame will not work.

 

References

To learn more about SafeFrames see:

 

 

OpenWrap Analytics

There are two types of reports available in PubUI.

 

1. Daily Scheduled Reports in PubUI:

This report is available in the dashboard. The report is in 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 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 is 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 publishers should work with the originating exchange to provide any related feedback.

 

2. Standard Reports Available in Analytics:

Currently there are 3 Wrapper reports available in Analytics. You can access these two reports from Analytics | Standard Reports. For more information about these reports, refer to Wrapper Analytics Reports documentation. 

 

Known Limitations

The following sections describe the current known limitations of OpenWrap.

 

Post-timeout bids

  • Currently, the default bid (db) flag is set only if the partner endpoint returns an error (internal server error, not found, and so on) or times out (it will not be set to 1).

 

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 creatives do 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 accounts from Rubicon to Rubicon Fastlane and get new IDs to map in OpenWrap.

Product Update June 13, 2018

OpenWrap v11.5.0

OpenWrap v11.5.0 is now available as a Nightly build in the Publisher UI.

All publishers using OpenWrap v11.3.0 or earlier should upgrade to OpenWrap v11.5.0. OpenWrap v11.5.0 addresses an issue in fetching consent data from Consent Management Platforms in the Prebid.js version included in OpenWrap v11.3.0. See Prebid.js Issue #2591 for details. 

OpenWrap v11.5.0 is a fully tested and supported version of OpenWrap. The UI provides an alert when a Nightly build is selected, however, the warning is not applicable to v11.5.0. To continue supporting publishers who have not updated from Prebid v0.3x based versions, we have not yet updated our Prebid 1.x based versions to be the "Stable" OpenWrap version.

 

OpenWrap Using Prebid 1.13.0

OpenWrap Version Nightly - v11.5.0 runs on Prebid.js version 1.13.0.

 

OpenWrap v11.5.0 includes Consent Management Platform Support. See OpenWrap Updates - May, 09,2018 for details on enabling and configuring Consent Management Platform Support.

 

Returning Bidder Adapters

OpenWrap v11.5.0 adds back the following bidder adapters that are were missing from OpenWrap versions using Prebid 1.x:

 

  • Criteo
  • Index Exchange

 

Adapters Processing GDPR Consent Fields

The following adapters process consent fields as of OpenWrap version v11.5.0:

 

  • AdForm
  • AOL
  • AppNexus
  • bRealtime
  • Criteo
  • DefyMedia
  • DistrctM
  • Improve Digital
  • Index Exchange
  • OpenX
  • PubMatic
  • PulsePoint
  • Rubicon Project
  • Sekindo Universal McCann
  • Smart
  • Sonobi
  • Sovrn
  • WideSpace

 

Index Exchange Adapter Change

The Index Exchange bidder adapter in OpenWrap v11.3.0 uses the bidder code ix where older versions used the bidder code indexExchange. Publishers who are upgrading from an earlier version, monetizing through Index Exchange, and using partner-targeted line items in their ad server, must add new line items that use the new bidder code. 

 

Known Issues

As of OpenWrap version v11.5.0, the following bidders available in earlier versions, are not available in this version.

 

  • Triple Lift

 

 

 

 

⇧ Top

Attachments

    Outcomes