Supported Parameters and Testing - PubMatic/android-openwrap-ima-sample GitHub Wiki
The OpenWrap module provides various fields and methods for passing information such as demographics, custom key-value pairs, and privacy compliance related parameters like CCPA, GDPR, etc. The following sections provide the information required to pass additional parameters or configure settings.
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.getInstance().setEnableGDPR(<GDPR state>);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.getInstance().setGdprConsent(<#Base64ConsentString#>);The CCPA string lets publishers comply with the California Consumer Privacy Act (CCPA).
POWConfiguration.getInstance().setCCPAString(<#CCPAString#>);The Identifier for Advertisers (IDFA) lets your app receive targeted ads with higher relevancy for its users and greater monetization for you. 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.getInstance().setHashTypeForAdvertisingId(<HashType>);Pass app details to OpenWrap as follows:
- A valid store URL, containing the app ID of your app, must be passed. See the samples below for details.// Set application info
POWApplicationInfo applicationInfo = new POWApplicationInfo(this);
// If the site/app falls under multiple IAB categories, you can send the categories separated by a comma.
applicationInfo.setCategories("IAB-1, IAB-2");
// App Domain
applicationInfo.setDomain("Sports");
// Set if application is a paid app or not
applicationInfo.setPaid(true);
// Required: A valid app Store URL for your Android app.
applicationInfo.setStoreURL(<Your app's store URL>);
// Set app info to be used for the ad request
POWConfiguration.getInstance().setAppInfo(applicationInfo);The OpenWrap module's default timeout is five 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.setNetworkTimeout(<#Timeout_in_seconds>);Pass the bidder-specific custom parameters in the form of a JSONObject. The JSONObject should contain partner-specific keywords, in the format of { "<partner_name>": { "keywords": [ { "key" : "<key_name>", "value": }, ... ] } }. Please check the example below:
// Create ad request
POWAdRequest adRequest = ...;
// Set bidder specific custom key-values. For example:
JSONObject customJSON;
try {
customJSON = new JSONObject("{\"pubmatic\":{\"keywords\":[{\"key\":\"dctr\",\"value\":[\"val1\",\"val2\"]}]},\"appnexus\":{\"keywords\":[{\"key\":\"key1\",\"value\":[\"val1\",\"val2\"]},{\"key\":\"key2\",\"value\":[\"val1\"]}]}}");
adRequest.setBidderCustomParams(customJSON);
} catch (JSONException e) {
e.printStackTrace();
}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 = new POWUserInfo();
// User city
userInfo.setCity("NewYork");
// User Country
userInfo.setCountry("USA");
// Designated market area (DMA) code of the user. This field is applicable for US users only.
userInfo.setMetro("US");
// Home zip code for the U.S.; otherwise it indicates the postal code
userInfo.setZip("123");
// User gender
userInfo.setGender(POWUserInfo.Gender.MALE);
// Birth year in YYYY format.
userInfo.setBirthYear(1995);
// User's location coordinates
userInfo.setLocation(new POWLocation(POWLocation.Source.GPS, 74.58d, 63.87d));
// or
userInfo.setLocation(new POWLocation(<android.location.Location>));
// Set user info to be used for ad requests
POWConfiguration.getInstance().setUserInfo(userInfo);To pass extra key-value pairs in an OpenWrap request, use the keys in the following table and pass the values in string format.
| Key name | Meaning |
|---|---|
| pwtplbk | Playback Method. Please refer Playback Method |
| pwtdvry | Content delivery method i.e. 1 = Streaming, 2 = Progressive, 3 = Download |
| pwtvpos | Ad position. Please refer Ad position. |
| pwtvapi | String with list of Integers e.g. "5,6,7". Please refer API Framework |
| pwtgenre | Genre that best describes the content |
| pwttitle | Content title |
Example of passing extra key-values to OpenWrap:
// The playback method is 2, in other words: Initiates on Page Load with Sound Off by Default, so "pwtplbk":2
// Video ad position is fullscreen i.e. "pwtvpos":7
Map customConfigKV = new HashMap();
customConfigKV.put("pwtplbk", "2");
customConfigKV.put("pwtvpos", "7");
POWConfiguration.getInstance().setCustomKeyValues(customConfigKV);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 using versionId for an ad request. If you don't 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.setVersionId(2);Turn on bid response debugging as shown in the following sample.
// Create ad request
POWAdRequest adRequest = ...;
// Enable debug
adRequest.setDebugEnable(true);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 |