Supported Parameters and Testing - PubMatic/ios-openwrap-ima-sample GitHub Wiki
The OpenWrap module provides various fields and methods to pass information like demographics and key-value pairs, or to configure different compliance policies for CCPA or GDPR. The following sections provide the information required to pass additional parameters or configure settings.
Include the following header file if it doesn't already exist.
#import "POWConfiguration.h"
The following code samples help ensure that your ads comply with the General Data Protection Regulation (GDPR).
// Indicates whether or not the ad request is GDPR (General Data Protection Regulation) compliant.
[POWConfiguration sharedConfig].enableGDPR = YES;
The GDPR consent string indicates whether the user has granted consent to use their data and how their data may be used once it's obtained from the CMP partner or OpenRTB. Your app should base64-encode the consent string and make it URL-safe.
// A valid Base64 encoded consent string. See, https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework
[POWConfiguration sharedConfig].GDPRConsent = @"<#Base64ConsentString#>";
The CCPA string lets publishers comply with the California Consumer Privacy Act (CCPA).
[POWConfiguration sharedConfig].CCPA = @"<#CCPAString#>";
The Identifier for Advertisers (IDFA) lets your app receive targeted ads with higher relevancy for its users and greater monetization for you. For more information, see The Apple Developer Program License Agreement
Most DSPs will process only raw advertising IDs. As such, you'll achieve the best monetization by sending raw advertising IDs. If security requirements prohibit using the advertising ID in raw format, you can apply SHA1 or MD5 hashing to the advertising ID as shown in the following example. By default, it is sent in raw format.
[POWConfiguration sharedConfig].hashTypeForAdvertisingId = POWHashTypeSHA1;
Pass app details to OpenWrap as follows.
- A valid storeURL, containing the app ID of your app, must be passed.
See the sample below for details.
// Set application info
POWApplicationInfo *appInfo = [POWApplicationInfo new];
// A valid App Store URL of an iOS app is required.
appInfo.storeURL = @"https://itunes.apple.com/app/id378458261";
// If the site/app falls under multiple IAB categories, you can send the categories separated by a comma.
appInfo.categories = @"val1,val2";
// App Domain
appInfo.domain = @"pubmatic.sampleapp.com";
appInfo.paid = POWBOOLNo;
// Set app info to be used for ad request
[POWConfiguration sharedConfig].appInfo = appInfo;
OpenWrap module's default timeout is 5 seconds for bid requests. Applicable only for bid requests from configured partners; not for IMA's requests.
You can set a custom network timeout for OpenWrap requests.
// Create ad request
POWAdRequest *adRequest = ...;
// Set request timeout in seconds
adRequest.networkTimeout = <#Timeout_in_seconds>;
Pass the bidder-specific custom parameters in the form of a dictionary. The dictionary should contain partner specific keywords in the format of { "<partner_name>": { "keywords": [ { "key" : "<key_name>", "value": }, ... ] } }. Only use string or array of string as values. To set multiple values against the same key, use array. See the example below:
// Create ad request
POWAdRequest *adRequest = ...;
// Set bidder specific custom key-values.
adRequest.bidderCustomParams = @{ @"pubmatic": @{
@"keywords": @[@{
@"key": @"dctr",
@"value": @[@"val1", @"val2"]
}]
},
@"appnexus": @{
@"keywords": @[@{
@"key": @"key1",
@"value": @[@"val1", @"val2"]
},
@{
@"key": @"key2",
@"value": @[@"val1"]
}
]
}
};
Pass the user Information to OpenWrap using the following examples.
Note: PubMatic does not use user information internally for any targeting purpose.
// Set User Info info
POWUserInfo *userInfo = [POWUserInfo new];
// User city
userInfo.city = @"Rochester";
// User Country
userInfo.country = @"USA";
// Designated market area (DMA) code of the user. This field is applicable to US users only.
userInfo.metro = @"734";
// Home zip code for the U.S.; otherwise it indicates the postal code
userInfo.zip = @"14602";
// User gender
userInfo.gender = POWGenderMale;
// Birth year in YYYY format.
userInfo.birthYear = @1989;
// User's location coordinates
userInfo.location = [[CLLocation alloc] initWithLatitude:12.384 longitude:94.3];
// Set user info to be used for ad requests
[POWConfiguration sharedConfig].userInfo = userInfo;
To pass extra key-value pairs in an OpenWrap request, use the keys in the following table and pass the values in string/number format.
Key name | Data Type | Meaning |
---|---|---|
pwtplbk | NSString | Playback Method. Please refer Playback Method |
pwtdvry | NSNumber | Content delivery method i.e. 1 = Streaming, 2 = Progressive, 3 = Download |
pwtvpos | NSString | Ad position. Please refer Ad position. |
pwtvapi | NSString | String with list of Integers e.g. "5,6,7". Please refer API Framework |
pwtgenre | NSString | Genre that best describes the content |
pwttitle | NSString | Content title |
Example of passing extra key-values to OpenWrap:
// The playback method is 2,3 i.e. "Initiates on Page Load with Sound Off by Default" and
// "Initiates on Click with Sound On", so @"pwtplbk": @"2,3"
// Video ad position is fullscreen i.e. @"pwtvpos": @7
[POWConfiguration sharedConfig].customKeyValues = @{@"pwtplbk": @"2,3", @"pwtvpos": @7};
Before releasing your ad-enabled app into the world, you must first test that your integration is working correctly and debug as necessary. The following section will help you perform QA on your integration before going live.
Use this call to set a test profile versionId for an ad request. If you do not set a test profile versionId, then OpenWrap will default to the live version of your profile.
// Create ad request
POWAdRequest *adRequest = ...;
// Set OpenWrap profile version Id
adRequest.versionId = @<#Version_Id>;
Turn on bid response debugging as shown in the following sample.
// Create ad request
POWAdRequest *adRequest = ...;
// Enable debug
adRequest.enableDebug = YES;
The values below are from the IAB OpenRTB Spec v2.5.
Value | Description |
---|---|
0 | Unknown |
1 | Above the Fold |
2 | DEPRECATED - May or may not be initially visible depending on screen size/resolution. |
3 | Below the Fold |
4 | Header |
5 | Footer |
6 | Sidebar |
7 | Full Screen |
Value | Description |
---|---|
1 | VPAID 1.0 |
2 | VPAID 2.0 |
3 | MRAID-1 |
4 | ORMMA |
5 | MRAID-2 |
6 | MRAID-3 |
7 | VIEWABITY MEASUREMENT |
Value | Description |
---|---|
1 | Initiates on Page Load with Sound On |
2 | Initiates on Page Load with Sound Off by Default |
3 | Initiates on Click with Sound On |
4 | Initiates on Mouse-Over with Sound On |
5 | Initiates on Entering Viewport with Sound On |
6 | Initiates on Entering Viewport with Sound Off by Default |