Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info
titleThis 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

...

process

This table provides an overview of the integration process.

activities…
Info
titleEach integration activity is dependent Regarding integration timing:
  • Most integration activities are dependent on the completion of prior
If an
  • activities. If a dependent activity is not completed in the time required, it will delay subsequent activities
and 
  • and potentially increase 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.
  • The sample timeline below is for a simple integration (one or two properties, a few profiles, 3-5 bidders). Larger integrations take longer because of the repetition and/or volume of information to collect and implement.

If you have questions or concerns

about completing activities, please

, feel free to 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.


Activity

OwnerTime Required

Phase 1: Solution design (1 day)

ActivityOwnershipDetails
Information GatheringPubMatic
 & After the publisher

Publisher
3 Days
  1. 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
  1. Publisher reviews PubMatic's OpenWrap documentation and sends follow-up questions to PubMatic.
  2. Publisher reviews the demo page and identifies the appropriate API and tag for their production environment.  
      - JS API: OpenWrap Javascript API
      - JS hooks: OpenWrap Hooks for JS 
  3. PubMatic reviews the updated questionnaire, Wrapper functionality, and set up details with the publisher and then outlines the project plan.
Phase 2: Implement and test (2-3 days)
Inventory setup (sites & tags)PubMatic
Publisher
  1. Publisher provides a list of ad unit sizes for bidder setup
  2. PubMatic sets up bidder per these guidelines: Account Setup Guide for Publishers (Sites & Ad Tags)
 
  • 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. 
  • Send completed mapping file to PubMatic.
    Learn more: Mapping Ad Units
    Create Partner Profiles & Provide Partner Mapping DetailsPublisher
    2-5 Days

    Step One: Publisher obtain information

    Partner Profiles:

  • Contact each header tag vendor you work with to obtain the publisher id/equivalent.
  • Use OpenWrap to create profiles and configure partners. 
    Learn more: OpenWrap Profile Management 

    Mapping:

    1. PubMatic shares bidder-specific configuration template with the publisher
    2. Publisher connects with each bidder and obtains bid parameter details for respective bidder configuration
    3. Publisher shares the updated bidder-specific template with PubMatic for partner configuration, and PubMatic review the details to ensure no mismatches.
    Wrapper Profile Setup PubMatic
    3 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)

    PubMatic 

    Up to 1 week
    1. PubMatic reviews the profile configuration requirements with the publisher
    2. Publisher shares profile configuration values with PubMatic
    3. PubMatic prepares for profile setup based on Publisher’s input
    Ad server setup (order, line item, creative)

    PubMatic
    Publisher

    1. PubMatic shares the ad server configuration template with the publisher
    2. Publisher updates the ad server configuration template and sends it back to PubMatic
    3. Publisher (or PubMatic) creates the orders and line items in the ad server
    On-page setup & Integration TestingPubMatic
    Publisher
     
    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
    1. partner
    included.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
    1. who is included across a given profile.
    2. Verify that key/value pairs are passed to the ad server call.
    3. Verify that ad server is responding with the winning
    ‘creative’
    1. creative and that the creative is rendered.
    Soft Launch

    Publisher &

    PubMatic 

    Up to 1 week

    Phase 3: Launch and ramp (2-3 days)
    Account ramp

    PubMatic
    Publisher
     

    1. Copy wrapper tag to a live page
    (s) & provide the page(s) to PubMatic.
  • Verify line item setup. 
  • Once line items are created, repeat testing to ensure that the correct line items are invoked in response to the relevant bids.
  • Once
    1. and repeat the on-page setup & integration testing (from phase 2)
    2. Once verified, send test traffic of 100k impressions per day from a live web page
    .
    1. Perform discrepancy checks between OpenWrap analytics and ad server data
    .
  • Discrepancy should be below 20% per the ad server standard.
  • Go LivePublisherUp to 1 weekCopy wrapper tag code to entire website.
    1. Repeat these steps for each property set up and launch

    Integration options

    OpenWrap supports two integration options:

    ...

    Info

    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 parametersIntegrations Available in OpenWrap 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.

    ...

    UAS

    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. 

      Info
      There are different methods for rendering creatives for PMP bids and Open Market bids. Use the appropriate related script below


      SafeFrame for Rendering rendering PMP Bidsbids

      Code Block
      languagejs
      linenumberstrue
      <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 rendering Open Auction Bidsbids

      Code Block
      languagejs
      linenumberstrue
      <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. Check the box for Serve into a SafeFrame.
    3. Complete any other required fields and choose Save.
    Excerpt

    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.

    Examples:
    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
    pubmatic
    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

    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.

    ...

    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.

    ...

    • 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).

    Info
    titleTo 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. 

    ...