OpenWrap In-App v2.0.0 Developer Guide for DFP (iOS)

Document created by Pritesh.Lad on Feb 16, 2018Last modified by david.simerly on Mar 27, 2018
Version 37Show Document
  • View in full screen mode
Download the OpenWrap for iOS sample app—OpenWrap_iOS.zip.

Introduction

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

  1. The OpenWrap call is made before requesting an ad from the primary AdServer SDK.
  2. Programmatic buyers get first look at the inventory and submit a bid price.
  3. OpenWrap conducts a server-side auction between bids from different header bidding partners configured by the publisher and selects a winning bid.
  4. 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, and so on.

Prerequisites

Integration of 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

For this approach you'll use APIs to simply prefetch bids using PMPrefetchManager and 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.

 

  1. Creating a Prefetch Request
  2. Prefetching Bids Using PMPrefetchManager
  3. Handling Prefetched Bids From PMPrefetchManager
  4. Receiving a DFP App Event Callback
  5. Rendering Prefetched Creative

 

Creating a Prefetch Request

  1. Import PMPrefetchManager file as shown below.
    #import "PMPrefetchManager.h"
  2. 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:
    PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<ImpressionId> slotName:<slotName> sizes:<AdSizes>];
    impression.pmZoneId = @"123";
    [impression setCustomParam:@"paramValue" forKey:@"paramKey"];
    impression.supportedAPIs = PMAPI_MRAID_1 | PMAPI_MRAID_2 | PMAPI_ORMMA;
    <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.
  3. Create a prefetch request object by specifying the publisher id (pubId), profileId, and impressions, from step 2 above, to prefetch bids. It is required to make an ad request to PubMatic against impression objects. Your code should be similar to this:
    PMPrefetchRequest *prefetchRequest = [[PMPrefetchRequest alloc] initWithPublisherId:<pubId> 
                                           profileId:<profileId> impressions:<impressions>];
    [prefetchRequest setApplicationPaid: PMBOOLNo];
    [prefetchRequest setDma:@"734"];
    [prefetchRequest setCoppa:PMBOOLYES];
    [prefetchRequest setIABCategory:@"IAB1-1,IAB1-7"];

    <pubId> = publisher Id.

    <profileId> = wrapper Profile Id of the publisher.
    <impressions> = array of PMBannerImpression objects 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 PMPrefetchRequest object such as store URL, app domain, gender, and much more.

Prefetching Bids Using PMPrefetchManager

  1. Create PMPrefetchManager object.
    PMPrefetchManager *prefetchManager = [[PMPrefetchManager alloc] init]; 
    prefetchManager.delegate = self;
    Set a network timeout (In seconds) using maxNetworkTimeout property of PMPrefetchManager. Default network timeout is 3 seconds.
  2. Adopt the PMPrefetchDelegate and implement the delegate methods.
    - (void)prefetchManager:didReceiveBids: 
    - (void)prefetchManager:didFailWithError:
  3. Call prefetchCreativesForRequest: on PMPrefetchManager object created in step 1.

 

Handling Prefetched Bids From PMPrefetchManager

Upon success, the PMPrefetchManager delegate callback - (void)prefetchManager:didReceiveBids: responds with a map of PMBid objects.

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:

- (void)prefetchManager:(PMPrefetchManager *)prefetchManager didReceiveBids:(NSDictionary *)bids 
{
//Get single bid for impressionId
  PMBid *bid = bids[impressionId];
//Save these bids and use them for rendering ads later
}

 

Calling DFP ad with pre-fetched bid information.

Please note that prefetchManager:didReceiveBids: and 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.

 

  1. Create a DFPRequest object, providing it with all the targeting information using setCustomTargeting:

    //Create DFP Ad request
    DFPRequest *dfpRequest = [[DFPRequest alloc] init];
    //Set targeting parameters on DFP Ad request
    [dfpRequest setCustomTargeting:[bid targetingInfo]];
    targetingInfo dictionary contains: deal id (for key pwtdid), which is used for PMP deals; and bid status (for key pwtbst), which is used for reporting.
  2. Call loadRequest on Main thread: on DFPBannerView with the dfpRequest created in step 1.

    dispatch_async(dispatch_get_main_queue(), ^{ 
    [dfpView loadRequest:dfpRequest];
    });

 

Receiving a DFP App Event Callback

Every winning bid receives a DFP app event, which requires GADAppEventDelegate and the following method:

- (void)adView:(DFPBannerView *)banner 
didReceiveAppEvent:(NSString *)name
withInfo:(NSString *)info

name = app event name.

info = impressionId for which the wrapper bid has won.

 

Rendering Prefetched Creative

Fetch the 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 MRAID or VPAID ad.

See the OpenWrap for iOS sample app for an example of rendering a simple banner creative using a WebView.

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 (DFP). The PMWrapperManager handles fetching wrapper bids from PubMatic and handing over them to your wrapper object to initiate the ad server call.

 

Use the 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 PMWrapperProtocol.

 

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:

See the OpenWrap for iOS sample app for more details.
  1. Create a PMDFPWrapper object for each ad slot by providing slot name , list of ad sizes, and DFPBannerView.
    PMDFPWrapper *dfpWrapper = [[PMDFPWrapper alloc] initWithDFPBannerView:self.dfpView slotName:<slotName> 
    sizes:<validSizes>];
  2. Write code that makes the DFP ad server request in the requestAndLoadAd: method. The PMWrapperManager calls 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.
  3. Implement an impression method to return the PMBannerImpression object. PMWrapperManager uses this method to get an impression object representing your ad slot. Your code may be similar to this:
    PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<ImpressionId> slotName:<slotName> sizes:<AdSizes>];
    <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 PMSize objects for requesting an ad with different sizes.
  4. Create a list of these PMDFPWrapper objects, one wrapper object per ad slot.
  5. Create an object of PMWrapperManager with 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.
  6. Call loadAd on wrapper manager.
    self.wrapperManager = [[PMWrapperManager alloc] initWithPublisherId:<PublisherId> profileId:<ProfileId>
                            wrappers:<WrapperArray>];   
    self.wrapperManager.prefetchRequest.versionId = <VersionId>; //optional
    self.wrapperManager.refreshInterval = <RefreshInterval>;
    [self.wrapperManager loadAd];

    <pubId> = publisher Id.

    <profileId> = wrapper Profile Id of the publisher.

  7. 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 renderedViewForBid:: of 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 secondsBehavior
X <= 0Ad does not refresh.
X > 0 & X <= 12Ad refreshes every 12 seconds.
X > 12 & X <=120Ad refreshes every X seconds.
X > 120Ad refreshes every 120 seconds.
To use this feature, first disable the ad server's native refresh functionality.

 

App Debugging

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.

S.noPropertyDescription
1storeUrlURL of the app store from which a user can download your app. This URL must match the storeurl that is whitelisted in the UI.
2appDomainIndicates your app's domain.
3applicationPaidFlags whether your app is free or a paid versio. Possible values are:

PMBoolNo = free version.

PMBoolYES = paid version.

4applicationIdiOS application id
5pmZoneIdUse this parameter to pass a zone ID for reporting.
6birthYearVisitor's birth year as a four-digit integer; for example, 1975.
7gender

Gender of the visitor. Possible values are:

PMGenderMale = Male

PMGenderFemale = Female

PMGenderOther = Others

8cityCity of the user; for example, city=New York
9dmaStores the user's Designated Market Area (DMA) code; applicable to US users only.
10stateThe region code using ISO-3166-2; 2-letter state code if USA.
11zipHome zip code if the visitor lives in the U.S.; otherwise it indicates the postal code.
12coppa

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:

PMBoolNo = the visitor is not COPPA-specific and can be served targeted ads.

PMBoolYES = the visitor is COPPA-specific and should be served only COPPA-compliant ads.

See the United States Federal Trade Commission's comprehensive FAQ on complying with COPPA for more details.
13keywordsList of keywords indicating the consumer's interests or intent.
14locationLatitude, longitude of the client device location.
15locationSource

The user's location source may be useful to deliver geographically relevant ads. Possible values are:

  PMLocSourceGPS

  PMLocSourceIPAddress

  PMLocSourceUserProvided

16summaryDisabledDisables bid summary that is sent in the response if YES (default).
17versionId

Use to specify the wrapper version Id of the publisher. If not specified, OpenWrap uses the live version of the profile. The versionId parameter is sent in the request in debug mode only.

18isIDFAEnabledThis property is set to YES by default to use the advertisement id for ad targeting. Set this property to NO to use the vendor id for targeting instead. This property takes effect only when the user has disabled Limit Ad Tracking in the device privacy settings.
19udidHashType

Applies one of the following hashing types to the udid param value before sending it to the server:

PMUdidhashTypeRaw = 1 (Default value)

PMUdidhashTypeSHA1 = 2

PMUdidhashTypeMD5 = 3

20IABCategoryList 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.

S.no

Property/Method

Description

1

pmZoneIdUse this parameter to pass a zone ID for reporting.

2

setCustomParam:forKey: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.

3

adVisibility

Fold placement of the ad to be served. Possible values are:

PMAdVisibilityUnKnown

PMAdVisibilityAboveFold

PMAdVisibilityBelowFold

PMAdVisibilityHeader

PMAdVisibilityFooter

PMAdVisibilitySidebar

PMAdVisibilityFullscreen

If you are unable to determine ad visibility, set this parameter to PMAdVisibilityUnKnown. For interstitial impressions (that is, if the isInterstitial flag is set to YES), OpenWrap automatically uses the PMAdVisibilityFullscreen value for adVisibility.

4

isInterstitial

Indicates if the ad is an interstitial impression.

5

sizes

Valid ad sizes.

6

supportedAPIs

List of supported API frameworks for this impression. If an API is not explicitly listed, assume it to be unsupported.

Possible values: VPAID 1.0, VPAID 2.0, MRAID-1, ORMMA, MRAID-2.

OR'ed value signifying supported API frameworks.

 

Table 4: PMBid Properties/Methods.

S.No.

Property/Method

Description
1-(NSDictionary *)targetingInfoReturns targeting information required by the ad server.
2-(NSDictionary *)targetingInfoWithPricePrecision:(int)precision;Returns targeting information required by the ad server with specified price precision. For example, for precision = 2, a price value of 1.456 is rounded to 1.46.
3impIdImpression Id. Also used as a bid id.
4pricePrice/bid value.
5heightAn ad's vertical height.
6widthAn ad's vertical width.
7status

Bid status.

0 = for invalid/no bid.

1 = for valid bid.

8creativeIdCreative Id.
9nurlWin notice URL called by the exchange when a bid wins.
10creativeTagActual creative.
11dealIdDeal Id. Used for PMP deals
12summaryBid summary for debugging purpose.

 

PubMatic Mapping

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.

See OpenWrap User Guide for more details.

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.

The preferred option for the PubMatic TAM team is to support the order creation in DFP. The client just needs to provide trafficker-level access. Use PubMatic's order insertion tool to insert relevant orders into DFP and create granular line items.

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.

<script type="text/javascript" src="https://media.admob.com/api/v1/google_mobile_app_ads.js"></script>
<script type="text/javascript">
admob.events.dispatchAppEvent("pubmaticdm","%%PATTERN:bidid%%");
</script>

 

Pre-Launch Verification

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.
  • Use pwtecp as the targeting attribute. This is the bid eCPM from the OpenWrap auction.
  • Use pwtbst as 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.

There are several keys that OpenWrap sends over Ad Server call which can be targeted in Line Items. See Wrapper Keys Sent to DFP.

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

 

Sample Variations:

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

 

⇧ Top

Attachments

Outcomes