Download the OpenWrap for iOS sample app— OpenWrap_iOS.zip.
OpenWrap-InApp enables publishers to solicit multiple programmatic bids for their mobile in-app inventory. OpenWrap sends an initial ad call to one or more header bidding partners to solicit bids for inclusion in the ad server’s inventory allocation process.
High-Level Process Overview
- The OpenWrap call is made before requesting an ad from the primary AdServer SDK.
- Programmatic buyers get first look at the inventory and submit a bid price.
- OpenWrap conducts a server-side auction between bids from different header bidding partners configured by the publisher and selects a winning bid.
- This winning bid data (including bid eCPM and dealid) is included in the ad server call, which checks if any other buyers in the same priority tier can beat it. As a result, inventory gets allocated to the highest yielding buyer while respecting other publisher controls that may have been set up in the ad server.
OpenWrap primarily benefits publishers who use third party SDKs (for example,
DFP) to manage their ads. However,
DFP doesn’t allow publishers to effectively pull in programmatic buyers that compete against AdX and direct deals, so publishers are limited in the buyers they can use.
When a view with an ad slot in the publisher's app loads, the OpenWrap code sends a request to the OpenWrap S2S service for bids before calling the ad server. OpenWrap makes the bid requests in parallel instead of using a sequential waterfall and provides publishers with access to many sources of demand.
The diagram below shows how PubMatic non-SDK header bidder integrates with a publisher’s app.
You can also allow the winning bid to compete with prices available from the direct-sold ads.
The OpenWrap In-App provides the following benefits:
- All the demand sources are bidding at the same time, which replaces waterfall’s preferential ordering of buyers.
- Advertisers have a chance at obtaining the best ad inventory.
- Publishers have seen a monetization increase as high as 50%.
Supported Ad Format
This depends on the supportedAPIs parameter value you set on a PMBannerImpression object. This solution gives you full rendering control and applications use their own rendering capabilities to support specific API frameworks, such as MRAID1, MRAID2, VPAID, ORMMA, etc.
DFP SDK and
DFP banner ad view. You can find more details here.
In-App Code Integration
Download and refer to the OpenWrap for iOS sample app for faster and easier integration. Copy the highlighted OpenWrap folder into your own iOS app.
This solution provides two integration approaches. Use the approach that satisfies your requirements.
- Approach 1: Prefetch Bids Using PMPPrefetchManager & PMPrefetchRequest
- Approach 2: Using PMWrapperManager
Approach 1: Prefetch Bids Using PMPPrefetchManager & PMPrefetchRequest
For this approach you'll use APIs to simply prefetch bids using
PMPrefetchRequest. You get full control to make ad server (
DFP) requests by passing prefetched bid, then handling ad server mechanism to determine if the bid wins.
- Creating a Prefetch Request
- Prefetching Bids Using
- Handling Prefetched Bids From PMPrefetchManager
- Receiving a DFP App Event Callback
- Rendering Prefetched Creative
Creating a Prefetch Request
PMPrefetchManagerfile as shown below.
Create Impression objects that contain information about specific ad slots like impressionId (Unique identifier), slot name and sizes. You may optionally set pmZoneId, custom parameters and supported API framework for this impression. For example:
<ImpressionId>= identifies unique ad slot/banner of DFP on screen.
<SlotName>= it is a string identifier. It should be the same slot name mapped to the wrapper ad tag. See PubMatic Mapping.
<AdSizes>= array of PMSize objects for requesting an ad with different sizes. Create an array of these impression objects.
Create a prefetch request object by specifying the publisher id (
impressions, from step 2 above, to prefetch bids. It is required to make an ad request to PubMatic against
impressionobjects. Your code should be similar to this:
>= publisher Id.
profileId>= wrapper Profile Id of the publisher.
<impressions>= array of
PMBannerImpressionobjects created in step 2.Contact your Customer Success Manager to get publisher Id and profile Id.For additional parameter details, please refer to Table 2 in the PubMatic Prefetch API Parameter Details .
You can also specify additional targeting information on
PMPrefetchRequestobject such as store URL, app domain, gender, and much more.
Prefetching Bids Using PMPrefetchManager
Set a network timeout (In seconds) using maxNetworkTimeout property of
PMPrefetchManager. Default network timeout is 3 seconds.
PMPrefetchDelegateand implement the delegate methods.
PMPrefetchManagerobject created in step 1.
Handling Prefetched Bids From PMPrefetchManager
Upon success, the
PMPrefetchManager delegate callback
- (void)prefetchManager:didReceiveBids: responds with a map of
The keys for this map are impression ids. The
PMBid object contains 'targetingInfo' dictionary that contains impression id, status, price, and so on. Save these bids and use them for rendering ads later, if the wrapper bid wins. For example:
Calling DFP ad with pre-fetched bid information.
Please note that
prefetchManager:didFailWithError are called on secondary thread.
To do any UI work from these callbacks, dispatch it on main queue as shown below in step 2.
DFPRequestobject, providing it with all the targeting information using
targetingInfodictionary contains: deal id (for key
pwtdid), which is used for PMP deals; and bid status (for key
pwtbst), which is used for reporting.
loadRequeston Main thread: on
dfpRequestcreated in step 1.
Receiving a DFP App Event Callback
Every winning bid receives a
DFP app event, which requires
GADAppEventDelegate and the following method:
name = app event name.
impressionId for which the wrapper bid has won.
Rendering Prefetched Creative
PMBid object, for the winning impression id, from the bids you saved earlier in
(void)prefetchManager:didReceiveBids: callback of
PMPrefetchManager. This object contains the winning creative in the
creativeTag property. Use this to render the ad. For example, use a simple
WebView for a banner ad, or a custom
Approach 2: Using PMWrapperManager
This solution provides a standard way (
PMWrapperProtocol) to easily write your own wrapper class that takes care of making calls to the ad server (
PMWrapperManager handles fetching wrapper bids from PubMatic and handing over them to your wrapper object to initiate the ad server call.
PMWrapperManager class as a convenient way to integrate PubMatic's OpenWrap solution with an ad server; for example, DFP.
PMWrapperManager initiates prefetch requests to PubMatic and also to the DFP ad server requests through wrapper objects that implement
You can write your own wrapper class conforming to
PMWrapperProtocol and handle ad server specific implementation. Simply import
PMWrapperManager.h in your custom wrapper class and adopt
PMWrapperProtocol. For example, see the
PMDFPWrapper code below:
- Create a
PMDFPWrapperobject for each ad slot by providing slot name , list of ad sizes, and
- Write code that makes the DFP ad server request in the
PMWrapperManagercalls this method of your wrapper class by passing the bid from PubMatic to initiate the ad server call. Save this bid for rendering the ad later.
- Implement an
impressionmethod to return the
PMBannerImpressionobject. PMWrapperManager uses this method to get an
impressionobject representing your ad slot. Your code may be similar to this:
<ImpressionId>= identifies a unique DFP ad slot/banner on screen.
<SlotName>= a string identifier. It should be the same slot name mapped to the wrapper ad tag. See PubMatic Mapping.
<AdSizes>= an array of
PMSizeobjects for requesting an ad with different sizes.
- Create a list of these
PMDFPWrapperobjects, one wrapper object per ad slot.
Create an object of
PMWrapperManagerwith the wrapper object's list created in step 4 and a profile id. You can optionally set a version id. See the PubMatic Prefetch API Parameter Details section for more details.OpenWrap defaults to the live version of the profile if the version id is not set.
loadAdon wrapper manager.
<pubId>= publisher Id.
<profileId>= wrapper Profile Id of the publisher.
- The wrapper manager fetches bids from PubMatic and initiates DFP ad server calls through your wrapper objects by passing these bids.
Rendering The Ad
When the DFP ad server notifies that a PubMatic bid has won (for example, by sending the PubMatic specific app event in
PMDFPWrapper implemented above), use the
creativeTag from the bid stored in step 2 above and render the creative with your own implementation.
This solution also provides a simple banner rendering. Just call
PMWrapperManager and pass the bid stored in step 2. This returns a
PMWebView object with the rendered banner ad. Add this into the superview where you want to show the ad.
Setting Refresh Interval (Optional)
This solution provides an optional feature to auto-refresh the banner ad after a specified interval.
The auto-refresh feature is disabled by default with an interval of 0 seconds. You can enable this feature by setting the
refreshInterval property of
PMPrefetchManager with an interval of 12 to 120 seconds.
Table 1: Ad refresh behavior on setting refresh interval value.
|Value (X) in seconds||Behavior|
|X <= 0||Ad does not refresh.|
|X > 0 & X <= 12||Ad refreshes every 12 seconds.|
|X > 12 & X <=120||Ad refreshes every X seconds.|
|X > 120||Ad refreshes every 120 seconds.|
OpenWrap logs requests and responses from the PubMatic server in debug mode. The debug log can help determine whether or not OpenWrap is providing proper bids. The image below shows a log from the OpenWrap for iOS sample app.
PubMatic Prefetch API Parameter Details
Use the following properties to send targeting parameter values.
Table 2: PMPrefetchRequest Properties.
|1||URL of the app store from which a user can download your app. This URL must match the |
|2||Indicates your app's domain.|
|3||Flags whether your app is free or a paid versio. Possible values are:|
|4||iOS application id|
|5||Use this parameter to pass a zone ID for reporting.|
|6||Visitor's birth year as a four-digit integer; for example, 1975.|
Gender of the visitor. Possible values are:
|8||City of the user; for example, |
|9||Stores the user's Designated Market Area (DMA) code; applicable to US users only.|
|10||The region code using ISO-3166-2; 2-letter state code if USA.|
|11||Home zip code if the visitor lives in the U.S.; otherwise it indicates the postal code.|
Indicates whether the visitor is subject to COPPA (Children's Online Privacy Protection Act) compliance. COPPA specifies that visitors below age 13 cannot receive targeted ads. Possible options are:
See the United States Federal Trade Commission's comprehensive FAQ on complying with COPPA for more details.
|13||List of keywords indicating the consumer's interests or intent.|
|14||Latitude, longitude of the client device location.|
The user's location source may be useful to deliver geographically relevant ads. Possible values are:
|16||Disables bid summary that is sent in the response if YES (default).|
Use to specify the wrapper version Id of the publisher. If not specified, OpenWrap uses the live version of the profile. The
|18||This property is set to |
Applies one of the following hashing types to the
|20||List of IAB content categories for the application. See 5.1 Content Categories in the Open RTB 2.4 specifications document. If the site/application falls under multiple IAB categories, you can send comma-delimited categories.|
Table 3: PMBannerImpression Properties.
|Use this parameter to pass a zone ID for reporting.|
|Sets a custom parameter for a given key. You can set multiple values for a key by calling this method again with a different value for the same key. OpenWrap sends multiple values as a comma-delimited list for that key.|
Fold placement of the ad to be served. Possible values are:
If you are unable to determine ad visibility, set this parameter to
Indicates if the ad is an interstitial impression.
Valid ad sizes.
List of supported API frameworks for this impression. If an API is not explicitly listed, assume it to be unsupported.
OR'ed value signifying supported API frameworks.
Table 4: PMBid Properties/Methods.
|1||Returns targeting information required by the ad server.|
|2||Returns targeting information required by the ad server with specified price precision. For example, for |
|3||Impression Id. Also used as a bid id.|
|5||An ad's vertical height.|
|6||An ad's vertical width.|
|9||Win notice URL called by the exchange when a bid wins.|
|11||Deal Id. Used for PMP deals|
|12||Bid summary for debugging purpose.|
Inventory mapping for demand sources/header bidding partners configured in OpenWrap must be completed in PubMatic Wrapper UI. This process creates a wrapper profile where publishers can map Ad Server slots to partner specific ad units; for example, PubMatic ad tag, AppNexus placement ID, and so on.
Ad Server Setup (DFP)
In addition to in-app code integration, OpenWrap also requires at set of
DFP ad server line items with small price increments. The PubMatic Operations team creates these line items using an internal tool.
Publishers must provide trafficker level access to create these line items to the email id provided by the PubMatic operations team. The publisher decides the price granularity for the line items and informs the PubMatic operations team. The PubMatic Operations team will provide an Excel file containing the specification details upon request.
Manual Creation of Ad Server Line Items
For publishers who prefer to create their own ad server line items, this section explains how to set up the line items. OpenWrap passes bids to the ad server using key-value pairs added to the ad server tags dynamically, as explained in the sections above.
Step 1: Create a new order in DFP for OpenWrap with PubMatic as the advertiser and add the relevant details.
Step 2: Set the price and priority of the line items.
Step 3: Set targeting on the
pwtbst value as 1. DFP uses this for reporting purposes. Also set targeting on
pwtecp, which would be a winning bid from OpenWrap. You can set targeting on
pwtdid (depending on custom key-value targeting in DFP). For more information see, Best Practices for Creating Line Items in the Ad Server.
Step 4: Add the In-App Header Bidding API creative provided by PubMatic to the line item you created.
Before setting traffic live, PubMatic’s Solutions Engineering team assists publisher’s technical and ad operations teams in conducting pre-launch verification. Once verifications are completed the app is ready to go live. Post-launch, the PubMatic Operations team ensures that the publisher is achieving the desired results and will provide consultation to ramp up implementation.
Best Practices for Creating Line Items in the Ad Server
To control monetization through OpenWrap at a granular level, you may:
- Create multiple OpenWrap line items in the ad server for each ad unit, ad size, CPM range and geo.
pwtecpas the targeting attribute. This is the bid eCPM from the OpenWrap auction.
pwtbstas a targeting attribute. The value for this key must be 1 for all OpenWrap line items. This is used for reporting all wrapper line items in DFP and this key value is set in the Ad Server request by default by the SDK.
- Place the line items at different priorities based on their pricing and relevance.
While creating line items at multiple price points, we recommend you create line items with more granular pricing where the bid density is high.
If 80% of the bids are between $0 to $3, create line items at a $0.1 granularity. For other ranges you can create line items at a higher granularity.
30 line items between $0-$3 with rate increment of $0.1
- LineItem 1 (covers $0-$0.09) Targeting: pwtecp=0.01*,pwtecp=0.02*....,pwtecp=0.09*, rate=$0.05
- LineItem 2 (covers $0.10-$0.19) Targeting: pwtecp=0.1*, rate=$0.15
and so on for next 28 line items
15 Line items between $3-$8 with rate increment of $0.30
- LineItem 31 (covers $3.0-$3.29) Targeting: pwtecp=3.0*,pwtecp=3.1*,pwtecp=3.2*, rate=$3.15
- LineItem 32 (covers $3.30-$3.59) Targeting: pwtecp=3.3*,pwtecp=3.4*,pwtecp=3.5*, rate=$3.45
and so on for next 13 line items
12 Line items between $9-$20 with rate increment of $1.0
- LineItem 46 (covers $9.0-$9.99) Targeting: pwtecp=9.*, rate=$9.5
- LineItem 47 (covers $10.0-$10.99) Targeting: pwtecp=10.*, rate=$3.45
and so on for next 10 line items
A final high- priority line item for very high bids
- Line Item 58 (Covers $20 and above) Targeting: pwtecp=20*,pwtecp=21*,pwtecp=22*...... pwtecp=50*) rate= $21