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"

Pass GDPR and GDPR consent

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#>";

Set CCPA string

The CCPA string lets publishers comply with the California Consumer Privacy Act (CCPA).

[POWConfiguration sharedConfig].CCPA = @"<#CCPAString#>";

Manage Advertisement Identifier

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 information

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;

Set bid request timeout

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 bidder-specific key-value pairs

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 user information

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;

Pass extra key-value pairs

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};

Test and Debug

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.

Test profile with a staging version

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>;

Debug OpenWrap network call

Turn on bid response debugging as shown in the following sample.

// Create ad request
POWAdRequest *adRequest = ...;

// Enable debug
adRequest.enableDebug = YES;

Custom parameter values

The values below are from the IAB OpenRTB Spec v2.5.

Ad position (pwtvpos)

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

API Framework (pwtvapi)

Value Description
1 VPAID 1.0
2 VPAID 2.0
3 MRAID-1
4 ORMMA
5 MRAID-2
6 MRAID-3
7 VIEWABITY MEASUREMENT

Playback Method (pwtpblk)

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
⚠️ **GitHub.com Fallback** ⚠️