You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

OpenWrap Integration Guide

This documentation describes the process of integrating the wrapper tag in OpenWrap…

For more information about generating a wrapper tag see 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.

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 ad server 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

Each integration activity is dependent on the completion of prior activities…

If an activity is not completed in the time required, it will delay subsequent activities and  the overall time it takes to complete the integration. Please note which activities are noted as the publisher's responsibility and what the expected time requirements are associated with each. If you have questions or concerns about completing activities, please reach out to PubMatic.

An OpenWrap integration takes up to 5 weeks to complete and contains 3 main phases with the following activities. Refer to the table below for more information about details, ownership and specific time requirements.

  1. Information Gathering (3 Days).
  2. Account Setup (2 1/2 Weeks):
    • Inventory setup.
    • Create partner profiles.
    • Provide mapping details for other partners.
    • Wrapper profile setup.
    • Line item setup.
  3. Testing/Soft Launch (5-7 Days):
    • On-page setup & integration testing.
    • Soft Launch.


OwnerTime RequiredDetails
Information GatheringPubMatic & Publisher3 Days

After the publisher completes the OpenWrap Integration Questionnaire, a meeting between PubMatic and the publisher will be scheduled by PubMatic.

During this introductory phase, PubMatic and the publisher discuss OpenWrap functionality, line item setup, reporting and more, to be sure there is a clear understanding of OpenWrap and the integration process. 

Inventory Setup (Sites & Tags)PubMatic2 Days

Set up Sites & Tags in PubMatic.

Learn more: Account Setup Guide for Publishers (Sites & Ad Tags) 

Create Partner Profiles & Provide Partner Mapping DetailsPublisher2-5 Days

Step One: Publisher obtain information

Partner Profiles:

  1. Contact each header tag vendor you work with to obtain the publisher id/equivalent.
  2. Use OpenWrap to create profiles and configure partners. 

    Learn more: OpenWrap Profile Management 


  1. Obtain ad unit mapping information for the partners you work with. Each partner must create ad tag ids/equivalent and add them to the mapping file provided by PubMatic. 
  2. Send completed mapping file to PubMatic.

    Learn more: Mapping Ad Units
Wrapper Profile Setup PubMatic3 Days
  1. Upload the completed mapping file.
  2. Complete setup and generate tag.
  3. Push to staging when ready to test.
Line Item SetupPubMatic (primary) &  Publisher Up to 1 week

PubMatic customizes line items based on publisher requirements.

Provide go-ahead to PubMatic solutions engineer to set up line items in ad server:

  1. For DFP: create granular line items with small increments to target granular price ranges.
  2. For UAS: a single line item of type wrapper.
On-page Setup & Integration TestingPublisher (primary)


Up to 1 week
  1. Copy the wrapper tag to the test web page & provide test page to PubMatic.
  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.
Soft Launch

Publisher &


Up to 1 week

  1. Copy wrapper tag to a live page(s) & provide the page(s) to PubMatic.
  2. Verify line item setup. 
  3. Once line items are created, repeat testing to ensure that the correct line items are invoked in response to the relevant bids.
  4. Once verified, send test traffic of 100k impressions per day from a live web page.
  5. Perform discrepancy checks between OpenWrap analytics and ad server data.
  6. Discrepancy should be below 20% per the ad server standard.
Go LivePublisherUp to 1 week

Copy wrapper tag code to entire website.

Integration options

OpenWrap supports two integration options:

The JavaScript API is the most flexible method, we recommend using it if you have multiple wrappers on the page. For example, if you're running OpenWrap & Amazon TAM together, you should use the JavaScript API. If OpenWrap is the only wrapper on the page, you can use either method, but GPT patching is only available if you're using DFP or UAS as your ad server.

While GPT Patching continues to be supported, new implementations should the JavaScript API.

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

Refer to instructions provided in documents mentioned below according to your ad server.


Ad Server Configuration

If using SafeFrames, see SafeFrames.


Ad Server Configuration

PMP & PMP-G Support

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

SafeFrames (DFP Only)

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 renders in a frame 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 (for example, ads). This provides a line of communication that affords data collection and rich interaction (for example, ad expansion), unavailable within a Friendly 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="//">
    <script type='text/javascript'>
    	 (function() {
    		  try {
    			  window.PWT.sfDisplayPMPCreative(document, '%%PATTERN:pwtdeal_pubmatic%%', []);
              } catch (e) {}

    SafeFrame for Rendering Open Auction Bids

    <script src="//">
    <script type='text/javascript'>
        (function() {
            try {
                window.PWT.sfDisplayCreative(document, '%%PATTERN:pwtsid%%');
            } catch (e) {}
  2. Check the box for Serve into a SafeFrame.
  3. Complete any other required fields and choose Save.

Wrapper Keys Sent to DFP

Key NameExplanationSample Value
pwtecpThe eCPM of bid in USD up to 4 decimal places.1.4356
pwtbstBid Status Flag: will be 1 for positive bids.1
pwtdidDeal Id: in cases when a bid has an associated deal.XYZ-DEAL 123
pwtsidThe slot/bid id of the highest or winning bid.e7424477d70315b8a4bae5cff1887edf
pwtpidAll partner data organized by partner name.
Add a filter to retrieve data for a specific partner.

pwtpid - to retrieve all partner data by partner name.
pwtpid=pubmatic - to retrieve data only for PubMatic.

For partner names, see bidder codes in PreBid bidders documentation
pwtdeal_<BidderCode>Partner-specific dealID and dealChannel based targeting can be done using this key. Format of the value is: <DealChannel>_-_<DealId>_-_<BidId>.Key: pwtdeal_pubmatic
Value: PMPG_-_dealxyz_-_123456
pwtszThe size of the highest/winning bid.WxH: 300x250

SafeFrame Scenario and Results



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.      


To learn more about SafeFrames see:

Known Limitations

The following sections describe known limitations for OpenWrap.

Code Generation Performance

The table below shows how performance of API code generation with gulp execution varies according to the number of adapter partners.

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

This impacts flow, user flows, and API calls when:

  • Copying profile.
  • Pushing wrapper code to staging.
  • Mapping upload.


  • Expandable creative will not work correctly after rendering inside of a SafeFrame on Safari, IE11/Edge.
  • UAS does not support SafeFrame; only a DFP ad server supports SafeFrame.

Support for Previous Code Build

Upon a stable code release of OpenWrap (with Prebid), prior code builds are unsupported. All subsequent OpenWrap profile versions will use the new stable code build.

Rubicon Legacy Adapter Support

OpenWrap no longer supports Rubicon legacy adapter in any future code builds. Rubicon Legacy adapter works only in releases prior to OpenWrap (with Prebid).

To use Rubicon Fastlane…

Publishers must migrate Rubicon accounts to Rubicon Fastlane and get new IDs to map in OpenWrap.

IndexExchange Adapter

OpenWrap ignores bids from Index Exchange adapter in a non-SRA setup. Perform the SRA GPT setup process to make the IndexExchange adapter work in OpenWrap. 

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents