Prebid SDK 1.8: bid response callback and OMSDK

prebid-mobile/pbm-api/android/pbm-adunit-android.md

@@ -47,12 +47,62 @@ PB Ad Slot is an identifier tied to the placement the ad will be delivered in. T
 
 Trigger a call to Prebid Server to retrieve demand for this Prebid Mobile ad unit.
 
+#### Mopub & GAM
+
+By default, Prebid SDK uses inflection to determine the publisher ad server, one of Mopub or Google Ad Manager (GAM), to convert the Prebid's targeting keys (PBS bid keys, host and cache key) to trigger targeted line items. To render ads in ad servers other than Mopub or GAM, use the next section's 3rd party ad server support feature.
+
+
 **Parameters**
 
 - `adObj`: This is the ad server request object (for [Google Ad Manager](https://developers.google.com/android/reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest) and for [Mopub](https://developers.mopub.com/publishers/reference/android/MoPubView/)). If you do not wish to add any additional /custom key values to the ad server after the Prebid auction, pass `adObj` to the fetchDemand function, where Prebid SDK will set all the Prebid targeting keys as well as any keys added prior to auction
 - As of Prebid SDK 1.7, a publisher can optionally pass the Google Ad Manager `builder` object of the [Google Ad Manager Mobile Ads SDK](https://developers.google.com/android/reference/com/google/android/gms/ads/doubleclick/PublisherAdRequest.Builder) to pass custom keys to Google Ad Manager after the Prebid Auction
 - `onCompleteListener`: listener object
 
+#### 3rd Party Ad Server
+
+As mentioned in the previous section the default ad servers for Prebid SDK are Mopub and GAM. For 3rd part ad server support, the fetchDemand function has been extended to return the Prebid Server bidder key / values (targeting keys) to be passed to the ad server of choice. 
+
+In this mode, the publisher will be responsible for the following actions:
+* Call fetchDemand with extended targetingDict callback
+* Retrieve targeting keys from extended fetchDemand function
+* Convert targeting keys into the format for your ad server
+* Pass converted keys to your ad server
+* Render ad with Prebid Universal Creative or custom renderer
+
+
+**Function Callbacks**
+
+* `ResultCode`: enum [result codes](https://docs.prebid.org/prebid-mobile/pbm-api/android/pbm-api-result-codes-android.html)
+* `unmodifiableMap`: [Prebid Server Response targeting keys](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting)
+
+
+```
+func fetchDemand(completion: @escaping(_ result: ResultCode, _ kvResultDict: [String : String]?) -> Void)
+```
+
+{: .alert.alert-warning :}
+unmodifiableMap is an immutable object. Attempting to modify at runtime will throw an UnsupportedOperationException error. The reason for unmodifiableMap being an immutable object is to help protect accidental changes to the Prebid targeting keys. Doing so may result in revenue loss. If there is a desire to update, create or remove a key, making a copy of unmodifiableMap is recommended before passing to the ad server.
+
+
+Example:
+
+```java
+func loadMPRewardedVideo() {
+private void loadMPRewardedVideo() {
+
+    adUnit.fetchDemand(new OnCompleteListener2() {
+        @Override
+        public void onComplete(ResultCode resultCode, Map<String, String> unmodifiableMap) {
+            //copy  of unmodifiableMap. It is an extra step to avoid runtime exception during changing unmodifiableMap
+            Map<String, String> kvMap  = new HashMap<>(unmodifiableMap);
+            String mpKeywords = Util.convertMapToMoPubKeywords(kvMap);
+            adServerRewardedVideoManager.RequestParameters parameters = new adServerRewardedVideoManager.RequestParameters(mpKeywords);
+            adServerObject.loadRewardedVideo(ADUNITID_REWARDED, parameters);
+        }
+    });
+
+}
+```
 
 
 

prebid-mobile/pbm-api/android/pbm-targeting-params-android.md

@@ -113,6 +113,66 @@ storeUrl = TargetingParams.getStoreUrl();
 TargetingParams.setStoreUrl(storeUrl);
 ```
 
+
+### Open Measurment SDK (OMSDK)
+
+OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is elligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code.
+
+There three components to signaling support for OMSDK:
+* Partner Name
+* Partner Version
+* API code
+
+**Partner Name**
+
+This will be the [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. See below for configuration and examples
+
+#### omidPartnerName
+Open Measurement partner name. 
+
+```
+TargetingParams.setOmidPartnerName(string)
+```
+
+Examples:
+
+Swift
+```java
+TargetingParams.setOmidPartnerName("Google")
+```
+
+**Partner Version**
+
+The OMSDK version number the partner integrated with. See below for configuration and examples.
+
+
+#### omidPartnerVersion
+Partner's OMSDK version number implementation
+```
+TargetingParams.setOmidPartnerVersion(string);
+```
+
+Examples:
+
+Swift
+```java
+TargetingParams.setOmidPartnerVersion("1.0");
+```
+
+**API Code**
+
+Per OpenRTB 2.5, support for OMSDK is signaled using the imp.[media type].api field represented in Prebid SDK withing each ad format type under the parameters object. Refer to the documentation of the respective ad unit class.
+
+Example:
+```
+BannerAdUnit bannerAdUnit = new BannerAdUnit("PREBID_SERVER_CONFIGURATION_ID", 300, 250);
+bannerAdUnit.setUserKeyword("my_key", "my_value");
+BannerBaseAdUnit.Parameters parameters = new BannerBaseAdUnit.Parameters();
+parameters.setApi(Arrays.asList(new Signals.Api(6, 7)));
+```
+
+
+
 ### Inventory (Context) Keywords
 Context Keywords are a list of keywords about the app as referenced in OpenRTB 2.5 as app.keywords. Any keyword passed in the context keyword field may be passed to the buyer for targeting.
 

prebid-mobile/pbm-api/ios/pbm-adunit-ios.md

@@ -53,14 +53,88 @@ PB Ad Slot is an identifier tied to the placement the ad will be delivered in. T
 
 Trigger a call to Prebid Server to retrieve demand for this Prebid Mobile ad unit.
 
+#### Mopub & GAM
+
+By default, Prebid SDK uses inflection to determine the publisher ad server, one of Mopub or Google Ad Manager (GAM), to convert the Prebid's targeting keys (PBS bid keys, host and cache key) to trigger targeted line items. To render ads in ad servers other than Mopub or GAM, use the next section's 3rd party ad server support feature.
+
 **Parameters**
 
 `adObject`: adServer object to which the Prebid keys need to be attached.
 
 `completion`: Closure which receives one argument, the enum `ResultCode`. There is no return value.
 
-{% include alerts/alert_warning.html content="Ad Unit *User* keywords will be deprecated in favor of [targeting keywords](pbm-targeting-ios#user-keywords) for Prebid versions 1.2+. Support will continue for Ad Unit User Keywords as users migrate to targeting user keywords." %}
 
+#### 3rd Party Ad Server
+
+As mentioned in the previous section the default ad servers for Prebid SDK are Mopub and GAM. For 3rd part ad server support, the fetchDemand function has been extended to return the Prebid Server bidder key / values to be passed to the ad server of choice. 
+
+In this mode, the publisher will be responsible for the following actions:
+* Call fetchDemand with extended targetingDict callback
+* Retrieve targeting keys from extended fetchDemand function
+* Convert targeting keys into the format for your ad server
+* Pass converted keys to your ad server
+* Render ad with Prebid Universal Creative or custom renderer
+
+
+**Function callbacks**
+
+* `ResultCode`: enum [result codes](https://docs.prebid.org/prebid-mobile/pbm-api/ios/pbm-api-result-codes-ios.html)
+* `targetingDict`: [Prebid Server Response targeting keys](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#targeting)
+
+
+```
+func fetchDemand(completion: @escaping(_ result: ResultCode, _ kvResultDict: [String : String]?) -> Void)
+```
+
+Examples:
+
+Swift
+```swift
+func loadBanner() {
+
+    //adUnit is BannerAdUnit type
+    adUnit.fetchDemand { [weak self] (resultCode: ResultCode, targetingDict: [String : String]?) in
+
+        self?.adServerRequest.customTargeting = targetingDict
+        self?.adServerBanner.load(self?.adServerRequest)
+    }
+}
+
+
+func loadRewardedVideo() {
+    let adUnit = RewardedVideoAdUnit(configId: "1001-1")
+    adUnit.fetchDemand { [weak self] (resultCode: ResultCode, targetingDict: [String : String]?) in
+
+        //Publisher should provide support for converting keys into format of 3rd party ad server and loading ads
+        let keywords = convertDictToAdServerKeywords(dict: targetingDict)
+        AdServerLoadAds.loadAd(withAdUnitID: "46d2ebb3ccd340b38580b5d3581c6434", keywords: keywords)
+    }
+}
+```
+
+Objective-C
+```objective-C
+-(void) loadAdServerBanner {
+
+    //adUnit is BannerAdUnit Type
+    [self.adUnit fetchDemandWithCompletion:^(enum ResultCode resultCode, NSDictionary<NSString *,NSString *> * _Nullable targetingDict) {
+
+        [self.request setCustomTargeting:targetingDict];
+        [self.adServerView loadRequest:self.request];
+    }];
+}
+
+-(void) loadAdServerRewardedVideo {
+
+    //adUnit is RewardedVideoAdUnit Type
+    [adUnit fetchDemandWithCompletion:^(enum ResultCode resultCode, NSDictionary<NSString *,NSString *> * _Nullable targetingDict) {
+
+        NSString *keywords = [Utils.shared convertDictToMoPubKeywordsWithDict:targetingDict];
+        [adServerRewardedVideo loadRewardedVideoAdWithAdUnitID:@"46d2ebb3ccd340b38580b5d3581c6434" keywords:keywords ];
+
+    }];
+}
+```
 
 ### addUserKeyword
 

prebid-mobile/pbm-api/ios/pbm-targeting-ios.md

@@ -151,6 +151,77 @@ Targeting.shared.itunesID
 Targeting.shared.itunesID = itunesID
 ```
 
+### Open Measurment SDK (OMSDK)
+
+OMSDK is designed to facilitate 3rd party viewability and verification measurement for ads served in mobile app enviroments. Prebid SDK will provide the signaling component to Bid Adapters, by way of Prebid Server, indicating the impression is elligible for OMSDK support. Prebid SDK does not currently integrate with OMSDK itself, instead it will rely on a publisher ad server to render viewability and verification measurement code.
+
+There three components to signaling support for OMSDK:
+* Partner Name
+* Partner Version
+* API code
+
+**Partner Name**
+
+This will be the [IAB OMSDK compliant partner name](https://complianceomsdkapi.iabtechlab.com/compliance/latest) responsible for integrating with the OMSDK spec. See below for configuration and examples
+
+#### omidPartnerName
+Open Measurement partner name. 
+
+```
+Targeting.shared.omidPartnerName = "string"
+```
+
+Examples:
+
+Swift
+```swift
+Targeting.shared.omidPartnerName = "Google"
+```
+
+Objective C
+```objective_c
+Targeting.shared.omidPartnerName = @"Google";
+```
+
+
+**Partner Version**
+
+The OMSDK version number the partner integrated with. See below for configuration and examples.
+
+
+#### omidPartnerVersion
+Partner's OMSDK version number implementation
+```
+Targeting.shared.omidPartnerVersion
+```
+
+Examples:
+
+Swift
+```swift
+Targeting.shared.omidPartnerVersion = "1.0"
+```
+
+Objective C
+```objective_c
+Targeting.shared.omidPartnerVersion = @"1.0";
+```
+
+**API Code**
+
+Per OpenRTB 2.5, support for OMSDK is signaled using the imp.[media type].api field represented in Prebid SDK withing each ad format type under the parameters object. Refer to the documentation of the respective ad unit class.
+
+Example:
+```
+let bannerUnit = BannerAdUnit(configId: "6ace8c7d-88c0-4623-8117-75bc3f0a2e45", size: CGSize(width: 300, height: 250))
+let parameters = BannerAdUnit.Parameters()
+parameters.api = [Signals.Api(7)]
+adUnit.setParameters(parameters);
+```
+
+
+
+
 ## Inventory (Context) Keywords
 
 Context Keywords are a list of keywords about the app as referenced in OpenRTB 2.5 as app.keywords. Any keyword passed in the context keyword field may be passed to the buyer for targeting.