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

Document created by Pritesh.Lad on Feb 16, 2018Last modified by david.simerly on Jun 11, 2018
Version 48Show 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, MoPub) to manage their ads. However, MoPub 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.

 

OpenWrap In-App provides the following benefits:

 

  • All demand sources are bid at the same time, replacing waterfall’s preferential ordering of buyers.
  • Advertisers have a chance at obtaining the best ad inventory.
  • Publishers have seen a monetization lift of 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

Get started with MoPub integration for iOS using the guidelines in the MoPub SDK documentation.

 

In-App Code Integration

Copy the contents of the OpenWrap folder to the Publisher’s iOS application. Refer to PubMatic's OpenWrap for iOS sample app for faster and easier integration.

 

 

This solution provides two integration approaches. Use the approach that satisfies your requirements:

 

 

Approach 1: Prefetch Bids Using PMPPrefetchManager & PMPrefetchRequest

In this, you use APIs to simply prefetch bids using PMPrefetchManager and PMPrefetchRequest. You get full control on making ad server (MoPub) request by by passing prefetched bid and 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. Calling MoPub Ad With Pre-Fetched Bid Information
  5. Receiving Winning Impressions Using MoPub's Custom Event Handler
  6. Getting Rendered Ad from 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), slotName, and adSizes. You can optionally set the 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 MoPub on screen. This should match with imp_id configured at step 2 in Ad Server Setup (MoPub).
    <SlotName> = a string identifier that should be the same slot name mapped to the wrapper ad tag. 
    <AdSizes> = Array of PMSize objects for requesting an ad with different sizes.
  3. Create an array of the impression objects.
  4. Create a prefetch request object by specifying publisher id (pubId), profile id (profileId), and impressions, from step 2 above, to prefetch bids. It is required to make an ad request to PubMatic against impression objects.
    Sample code to create a prefetch request and set basic parameters:
    PMPrefetchRequest *prefetchRequest = [[PMPrefetchRequest alloc] initWithPublisherId:<pubId> profileId:<profileId> impressions:<impressions>];
    [prefetchRequest setPaid: PMBOOLNo];
    [prefetchRequest setDma:@"734"];
    [prefetchRequest setCoppa:PMBOOLYES];
    [prefetchRequest setIABCategory:@"IAB1-1,IAB1-7"];

    <pibId> = 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 section below.
  5. You can also specify additional targeting information on PMBannerPrefetchRequest object such as store URL, app domain, gender, ethnicity, 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.

    [prefetchManager prefetchCreativesForRequest: prefetchRequest ];

 

Handling Prefetched Bids from PMPrefetchManager

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

 

The keys for this map will be the 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.


Example:

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

 

Calling MoPub Ad With Pre-Fetched Bid Information

Please note prefetchManager:didReceiveBids: and prefetchManager:didFailWithError are called on a secondary thread. To do any UI work from these callbacks, dispatch it on main queue as shown below in step 2.

  1. Set bid details from PMBid object as keywords for MoPub ad.

     NSMutableString * keywords = [NSMutableString new];
    if (bid){
            NSDictionary * targetingInfo = [bid targetingInfoWithPricePrecision:1];
            for (NSString *key in targetingInfo) {
                [keywords appendFormat:@"%@:%@,",key,targetingInfo[key]];
            }
    }
    banner.keywords = [NSString stringWithString:keywords];
    (banner is an MPAdView object)
    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. Bid price is rounded to a single decimal digit.
  2. Call loadAd: on MPAdView instance

    dispatch_async(dispatch_get_main_queue(), ^{ 
    [banner loadAd]; 
    }); 

    <banner> = instance of MPAdView.

    Disable the auto-refresh feature on the MoPubView and use refreshInterval property of PMPrefetchManager to auto-refresh ad.

 

Receiving Winning Impressions Using MoPub's Custom Event Handler

The publisher must implement a custom event handler subclassing MoPub’s MPBannerCustomEvent.

 

For every winning bid, this event handler will receive event:

- (void)requestAdWithSize:(CGSize)size customEventInfo:(NSDictionary *)info 

The info dictionary contains the impressionId for which the header bid has won.

 

Getting Rendered Ad from Prefetched Creative

Fetch the PMBid object, for the winning impression id, from the bids you saved earlier in (void)prefetchManager:didReceiveBids: callback from PMPrefetchManager. This object contains winning creative in creativeTag property. Use this to render the ad. For example, using simple WebView for banner or a custom MRAID or VPAID capabilities you have.

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

Call bannerCustomEvent:didLoadAd: on the custom event class delegate if a valid ad is returned; for example, webview is not nil.

 

if (webview) { 
        [self.delegate bannerCustomEvent:self didLoadAd:webview];
    }else{
        
        MPLogInfo(@"Failed to render prefetched Ad creative");
        [self.delegate bannerCustomEvent:self didFailToLoadAdWithError:nil];
    }

 

Approach 2: Using PMWrapperManager

This solution provides a standard way (PMWrapperProtocol) to easily write your own wrapper class that handles making calls to the MoPub ad server. The PMWrapperManager handles fetching 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 the MoPub ad server.

PMWrapperManager initiates wrapper requests to PubMatic as well as the MoPub 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. See PMMoPubWrapper in the following steps.

See the OpenWrap for iOS sample app for more details.
  1. Create a PMMoPubWrapper object for each ad slot by providing slotName , a list of ad sizes, and MPAdView.

    PMMoPubWrapper *moPubWrapper = [[PMMoPubWrapper alloc] initWithMoPubBannerView:self.moPubBannerView slotName:<slotName> sizes:<validSizes>];
  2. Write code that makes the MoPub ad server request in the requestAndLoadAd: method.

    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 the impression method to return the PMBannerImpression. PMWrapperManager uses this method to get the impression object representing your ad slot.

    PMBannerImpression *impression = [[PMBannerImpression alloc] initWithImpressionId:<ImpressionId> slotName:<slotName> sizes:<AdSizes>];

    <ImpressionId> = identifies a unique ad slot/banner of MoPub on screen. This should match with imp_id configured at step 2 in Ad Server Setup (MoPub) section below.
    <slotName> = a string identifier that 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 such PMMoPubWrapper objects, one wrapper object to represent a single 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 version id.

    OpenWrap uses the live version of the profile by default 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.

    The wrapper manager fetches bids from PubMatic and initiates ad server calls through your wrapper objects by passing the bids.

 

Rendering The Ad

Once the ad server notifies that the PubMatic bid has won—for example, by using MoPub custom event—use the creativeTag from the bid stored in step 2 above to render the creative with your own implementation.


This solution also provides a simple banner rendering. Just call renderedViewForImpressionId:: of PMWrapperManager and pass the impression id for your ad slot. This returns an object of PMWebView with a rendered banner ad. Pass this to your banner custom event delegate(bannerCustomEvent:didLoadAd:).

 

Setting Refresh Interval (Optional)

This solution provides an optional feature to auto-refresh the banner ad after a specified interval.

 

The default value for refresh interval is 0 seconds; that is, by default auto-refresh feature is disabled. You can set an appropriate refresh interval using the refreshInterval property of PMPrefetchManager. Expected value should be in the range of 12 to 120 seconds.

Table 1: Ad refresh behaviour on setting refresh interval value:

Value (X) in secondsBehaviour
X <= 0Ad will not refresh
X > 0 & X <= 12Ad will get refreshed after every 12 seconds.
X > 12 & X <= 120Ad will get refreshed after every X seconds
X > 120Ad will get refreshed after every 120 seconds
To use this feature, please disable the ad server’s native refresh functionality. See the MoPub portal documentation for additional information.

 

App Debugging

OpenWrap In-App code logs the request and response from the PubMatic server in debug mode. This debug log can help determine whether PubMatic is providing proper bids or not. Below are sample logs from the OpenWrap for iOS sample app.

 

 

PubMatic Prefetch API Parameter Details

Use the following properties for sending targeting parameter values.

 

Table 2: PMBannerPrefetchRequest properties

S.no

Property

Description

1

storeUrl

URL of the app store from where a user can download this application. This URL must match the storeurl that is whitelisted in the UI.

2

appDomain

Indicates the domain of the mobile application

3

applicationPaid

Indicates whether the mobile application is a paid version or not. Possible values are:

PMBoolNo - Free version

PMBoolYES - Paid version

4

applicationId

iOS application id

5

pmZoneId

This parameter is used to pass a zone ID for reporting.

6

birthYear

Visitor's birth year as a four-digit integer. For example, 1975.

7

gender

Gender of the visitor. Possible values are:

PMGenderMale - Male

PMGenderFemale - Female

PMGenderOther - Others

8

city

City of the user. For example, city=New York

9

dma

You can set Designated market area (DMA) code of the user in this field.

This field is applicable for US users only

10

state

The region code using ISO-3166-2; 2-letter state code if USA.

11

zip

Home zip code if the visitor is present in the U.S.; otherwise it indicates the postal code.

12

coppa

Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's Online Privacy Protection Act) compliance, if the visitor's age is below 13, then such visitors should not be served targeted ads.

 

Possible options are:

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

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

The United States Federal Trade Commission has written a comprehensive FAQ on complying with COPPA at http://business.ftc.gov/documents/Complying-with-COPPA-Frequently-Asked-Questions.

13

keywords

list of keywords indicating the consumer's interests or intent.

14

location

Latitude, longitude of the device location

15

locationSource

The user's location source may be useful in delivering geographically relevant ads

Possible values are:

PMLocSourceGPS,

PMLocSourceIPAddress,

PMLocSourceUserProvided

16

summaryDisabled

Disables bid summary that is sent in the response, if YES.

Default YES.

17

versionId

This is used to specify Wrapper version Id of the publisher. If this is not specified, live version of the profile is considered.
'versionId' parameter will be sent in the request in debug mode only.

18

isIDFAEnabled

If set, it uses advertisement id otherwise it uses vendor id for targeting.

 

This has effect only if ‘Limit Ad Tracking’ is disabled on the user’s device privacy settings.

19

udidHashType

 

Use to apply the following hashing on udid param value before sending to server:

PMUdidhashTypeRaw = 1 (default)

PMUdidhashTypeSHA1 = 2

PMUdidhashTypeMD5 = 3

20

IABCategoryegory

List of IAB content categories for the application. Refer the "Table 5.1 Content Categories" in the Open RTB 2.4 specifications document. If the site/application falls under multiple IAB categories, you can send categories separated by comma.

 

Table 3: PMBannerImpression properties

S.no

Property/Method

Description

1

pmZoneId

This parameter is used to pass a zone ID for reporting.

2

setCustomParam:forKey:

Sets a custom parameter for given key. You can set multiple values for a key by calling this method again with different value for the same key. These will be sent as comma separated values 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 adVisibility, use the default value, PMAdVisibilityUnKnown. For interstitial impression (if isInterstitial flag is set to YES),  then use PMAdVisibilityFullscreen.

4

isInterstitial

Indicates if its 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, it is assumed not to be supported.

 

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, that needs to be sent to ad server.
2-(NSDictionary *)targetingInfoWithPricePrecision:(int)precision;Returns targeting information, that needs to be sent to ad server with specified price precision.
For example, for precision = 2, price value of 1.456 will be used as 1.46.
3impIdImpression Id. Also used as a bid id.
4pricePrice/bid value.
5heightThe ad's vertical height.
6widthThe ad's horizontal width.
7statusBid status.
1 - for valid bid.
0 - for invalid/no bid.
8creativeIdCreative Id
9nurlWin notice URL called by the exchange if the 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 the PubMatic Wrapper UI. This process creates a wrapper profile where publishers map Ad Server slots to the 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 (MoPub)

The following steps enable MoPub ad server to allocate impressions to PubMatic based on actual bid price and PubMatic's recommendation. Data are passed to the ad server using key-value pairs added to the MoPub ad request using PubMatic OpenWrap In-App code.

Publishers must provide trafficker level acces (able to create line items), to the email id provided by the PubMatic operations team.

Step 1: Create a new order in MoPub for In-App Header Bidding API with PubMatic as the advertiser and add the relevant details.

 

Step 2: Set the price and priority of the line items.

  • For the Type & Priority drop-downs, choose Network for Type and 12 for Priority (to enable PubMatic’s response to compete with MoPub Marketplace and Ad Networks).
  • Next select Network > Custom Native Network.
  • In the Class field, enter the name of an adapter class (subclass of CustomEventBanner class).
  • In the Data field, enter a map of <imp_id>:<adunit_id>. Add <imp_id>; same as impression id passed in PMBannerImpression.

 

 

Step 3: Ad unit targeting. Assign line items to appropriate ad units.

 

Step 4: In the Keywords list, set targeting on the pwtbst value as 1 from the Openwrap response. In addition to the pwtbst, set targeting on pwtecp, which would be a winning bid from OpenWrap. You can also set targeting on pwtdid (depending on custom key-value targeting). For more information see Best Practices for Creating Line Items in the Ad Server.

Key value targeting

 

Pre-Launch Verification

Before setting traffic live, PubMatic’s Solutions Engineering team will assist the publisher’s technical and ad operations teams conduct pre-launch verification. Once verifications are complete the setup is ready to go live on a small number of sites. Post-launch, the PubMatic Operations team will ensure that the publisher is achieving the desired results and will provide consultation to ramp up the implementation.

 

Best Practices for Creating Line Items in the Ad Server

To control monetization through OpenWrap In-App at a granular level, you can:

 

  • 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.
  • Place the line items at different priorities based on their pricing and relevance.
Important Notes:
  • Currently, PubMatic supports (one decimal point) 10-cent granularity in key-value targeting.
  • The maximum length of the keywords that MoPub supports is 10K characters. As a result, you can add approximately 300+ bid values in each line item, assuming each targeting line has 30 characters.
Example:
These line items match any ad request containing keyword "pwtbst:1, pwtecp:0.#" (# between 0 to n):

 

pwtecp:0.1 AND pwtbst:1
pwtecp:0.2 AND pwtbst:1
pwtecp:0.3 AND pwtbst:1
...
pwtecp:0.n AND pwtbst:1

 

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: bid=0.01,bid=0.02....,bid=0.09, rate=$0.05
  • LineItem 2 (covers $0.10-$0.19) Targeting: bid=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: bid=3.01,bid=3.1,bid=3.2, rate=$3.15
  • LineItem 32 (covers $3.30-$3.59) Targeting: bid=3.3,bid=3.4,bid=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: bid=9, rate=$9.5
  • LineItem 47 (covers $10.0-$10.99) Targeting: bid=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 : bid=20,bid=21,bid=22...... bid=50) rate= $21

 

⇧ Top

Attachments

Outcomes