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-sideThe 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.
PartnersSSP/Exchanges whose header tag is included in the wrapper.
ProfileDefines inventory for the wrapper. Includes configuration settings for the OpenWrap.
Server-sideAd 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.
VersionA 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 TagJavaScript (JS) code that includes multiple header tags, in addition to configuration, management, and analytics code. 


OpenWrap key features and functions

PubMatic OpenWrap:

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:

  4. Access to Ad server: Provide trafficker level access to the PubMatic team to assist with creating line items in the ad server. This is required if the publisher's ad server is GAM.

Getting started

Use the instructions in this section to configure OpenWrap. 

When you see DFP mentioned in this guide, it is referring to GAM. This will be updated in the Publisher UI in an upcoming release.

Log in and navigate to OpenWrap

  1. Select Inventory > OpenWrap. There are three OpenWrap tabs:

     

Add a partner

Before you edit profiles and generate tags, you must first add them in the Partner Management tab.

  1. From the Partner Management tab, choose Add Partner.
  2. Choose Bidder. See Identity Solutions for instructions on setting up Identity Hub.
  3. Select a partner from the Partner menu.
  4. Enter an Account Name (if you have multiple accounts with a partner, use a naming convention that will help you identify each partner account).
  5. Add the required information for each partner (for example, HostAccount AliasDomainNetwork ID, and so on—obtain this information from your partner if you don't already have it).
  6. Choose Save.

Edit a partner

Follow these steps to edit account-level information. 

  1. From the Partner Management tab, click the Actions menu next to the partner name.
  2. Make your edits and and choose Save.

Profile management

Profiles define groups of inventory that use the same configuration settings. Manage your profiles in 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 most settings. For example:

Add a new profile version

  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. Use the instructions below for the Edit Profile dialog that matches your configuration:

Client-side partner profiles

  1. Make changes to the Traffic AllocationBid Adjustment, and Timeout (ms) fields.


    Continue to the Add or Remove Partners section below.


Server-Side Partner Profiles

  1. Make changes to the Traffic AllocationBid 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.


    If all partners in the profile are configured as server-side, make sure at least one of them has 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 the timeout is more than 500, server-side component would cap the timeout for outbound bid requests to 500 ms.


    Continue to the Add or Remove Partners section below.


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 CUSTOM from the list.

Release Version

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

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 (GAM).

Ad Server is DFP.

Currency Conversion

  1. Select Enable to ensure partner bids in other currencies are converted to USD.
  2. Select USD from the AdServer Currency dropdown to use as your base currency.

    Platform is Display and Ad Server is DFP or CUSTOM.


Consent Management for GDPR

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.


When you have finalized all settings and have completed mappings as mentioned earlier in this guide, you will have a new DRAFT version.

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.


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

Create SafeFrame Line Items in  DFP (GAM)

  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 GAM, SafeFrame creative code added but the 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 GAM, 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.


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

Limitations

References

To learn more about SafeFrames see: 

Known Limitations

The following sections describe the current known limitations of OpenWrap.

Post-timeout bids

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:

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.

Support for Video on Server Side

For display profile in OpenWrap, currently we don't support server side partners for video inventory.