There are four main steps to complete before going live with OpenWrap. The goal of this document is to guide you through the process and highlight key decisions you'll need to make. We've also included links to other helpful documentation. Please note that these steps don't have to be done in order; they can be done in parallel, with the exception of a few overlapping decisions. The four steps are:
Ad slot mapping
Ad slot mapping is where you'll communicate to your bidding partners which ad slots you will be submitting for OpenWrap bids. The final output for each bidder is a CSV document where each row contains the ad unit path or div ID of the ad slot, the size, and some other columns that are completed by the bidding partner. The PubMatic UI provides you with a template containing the columns for each bidding partner.
The slot mapping CSV also determines how granular the reports provided by each bidding partner will be. A few highlights to keep in mind about reporting:
- If the exact ad unit name and size are not included in the CSV, then your bidding partners will most likely not bid on it.
- Your CSV should have a unique ID for each row in your mapping to ensure your bidding partners can break down their reports by those individual IDs.
- If each slot name has the same ID across multiple sizes, this is fine as long as each bidding partner can also include a column in the reports for size.
Create a GAM order
PubMatic has an automated line item tool to create orders in GAM. It generally takes ten minutes per order. We will go through all the options with you, but a few things to think about in preparation for our GAM order call:
- What do you want to name the order(s)?
- Do you want a separate order for each bidding partner?
- What size creatives do you want? (These should include all the sizes in your slot mappings, plus any sizes you may want to use in the future.)
- How many creatives of each size do you need? (Think about the total number of slots on the page and double or triple it if you use infinite scroll.)
- Do you want SafeFrames or friendly iframes? (If you are unsure, ask your bidding partners which they recommend.)
- Is there a specific placement that you want to target for these rs?
- Is there any custom targeting you want applied to the order?
OpenWrap code on a test page
After you have an OpenWrap profile created in your account and have a test order in GAM, you have everything you need to put OpenWrap code on a test page. We can show you test pages before you have these, but it will not mean as much to your developers if the test page is using a demo account. A high-level overview of what the code needs to perform:
GPT.js), unless you are using a different ad server.
- Define the GAM ad slots.
- Create the <div> for each slot.
- Initiate a round of OpenWrap bidding by calling
- The first argument in this function is the array of slots you are sending for bids. If you want to use all the slots on the page, we have a function to grab all of them. If you want to only send a subset of those slots or want to pass custom ad unit names, you will need to manually create this array in your code.
- The second argument in this function is the callback function we trigger when the round of bidding comes back.
- Apply the winning bid to each ad slot by calling
- Sending the slots up to GAM by calling
Steps 2, 3, 4, and 7 are probably already being done in the code with your GAM ad slots, so inserting OpenWrap into your ad stack will probably not require much engineering effort.
Here are three other common use-cases to keep in mind as you plan out your code:
- Infinite scroll and inserting new ad units on the page requires you to submit a new round of bidding and apply those key-values (steps 5 and 6 above) before calling
googletag.display()on the new ad units
- If you are refreshing ad units, you will need code on the page to initiate a new round of bidding before each ad refreshes:
PWT.removeKeyValuePairsFromGPTSlots(array_of_slots)to remove the key-values from the previous round of bidding
requestBids([adUnits],callbackFunction)to initiate the new round of bidding
PWT.addKeyValuePairsToGPTSlots(array_of_slots)after the new bidding ends in order to apply the winning bid details to the ad units
- If you are using another wrapper on the page, like A9, both rounds of bidding would be in parallel and independent of each other. You do need, however, a line of code to play "traffic cop" on the page to make sure both wrappers have completed their round of bidding and applied their key-value pairs to the ad units before calling
googletag.display()to send the ad request to GAM.
Detailed checklist of specific OpenWrap items you should verify as part of your team's QA process:
- Are we dynamically setting a specific OpenWrap profile to load on various pages?
- Are all slots are being sent to all bidding partners?
- Are we are seeing non-no bid responses from each bidding partner?
- Are we seeing any error responses in the console or network requests?
- Is the winning bid's details being sent to GAM in the
- If you force a winning bid price in the OpenWrap staging environment, does the PubMatic sample ad appear on the test page?
- Are the two analytics pixels (bid logger & win tracker) being sent to PubMatic?
- Are the cookie sync network requests being sent to all bidding partners?