Mobile: update docs for setORTB functions

_includes/mobile/adunit-config-android.md

@@ -1,5 +1,30 @@
 Each ad unit in the Original API is a subclass of the `AdUnit` class, which provides the following properties and methods for additional configuration.
 
+### Arbitrary OpenRTB
+
+(requires SDK v2.4.0)
+
+Prebid SDK allows the customization of the OpenRTB request on the impression level using the `setImpORTBConfig()` function: 
+
+``` kotlin
+adUnit.setImpOrtbConfig(
+        "{" +
+                "  \"bidfloor\": 0.01," +
+                "  \"banner\": {" +
+                "    \"battr\": [1,2,3,4]" +
+                "  }" +
+        "}"
+);
+```
+
+The parameter passed to `setImpOrtbConfig()` will be merged into the respective `imp` object for this Ad Unit. For instance, the above example will add the `$.imp[0].bidfloor` and `$.imp[0].banner.battr` parameters to the bid request.  
+
+To empty out a previously provided impression config, just set it to the empty string: 
+
+``` swift
+adUnit.setImpOrtbConfig("")
+```
+
 ### Auto Refresh
 
 #### setAutoRefreshPeriodMillis

_includes/mobile/adunit-config-ios.md

@@ -1,11 +1,29 @@
 Each ad unit in the original integration method is a subclass of the `AdUnit` class, which provides the following properties and methods for the additional configuration.
 
+### Arbitrary OpenRTB
+
+(requires SDK v2.4.0)
+
+Prebid SDK allows the customization of the OpenRTB request on the ad unit level using the `setImpORTBConfig()` function: 
+
+``` swift
+adUnit.setImpORTBConfig("{\"bidfloor\":0.01,\"banner\":{\"battr\":[1,2,3,4]}}")
+```
+
+The parameter passed to `setImpORTBConfig()` will be merged into the respective `imp` object for this Ad Unit. For instance, the above example will add the `$.imp[0].bidfloor` and `$.imp[0].banner.battr` parameters to the bid request.  
+
+To empty out a previously provided impression config, just set it to the empty string: 
+
+``` swift
+adUnit.setImpORTBConfig("")
+```
+
 ### Autorefresh
 
 #### setAutoRefreshMillis
 {:.no_toc}
 
-If set on a given banner adunit, the `fetchDemand` function will be called every `periodMillis` until `stopAutoRefresh` is called. Each call to `fetchDemand` will invoke the `onComplete` function. This refresh only pertains to Prebid Mobile and not to any ad server refresh processes. It is suggested that the adServes refresh be turned off.
+If set on a given banner ad unit, the `fetchDemand` function will be called every `periodMillis` until `stopAutoRefresh` is called. Each call to `fetchDemand` will invoke the `onComplete` function. This refresh only pertains to Prebid Mobile and not to any ad server refresh processes. It is suggested that the adServes refresh be turned off.
 
 #### stopAutoRefresh
 {:.no_toc}

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

@@ -745,32 +745,50 @@ Parameters:
 
 ## Arbitrary OpenRTB
 
-(requires SDK v2.2.1)
+(requires SDK v2.4.0)
+
+Prebid SDK allows the customization of the OpenRTB request on the global level using `setGlobalOrtbConfig()` function: 
+
+``` kotlin
+TargetingParams.setGlobalOrtbConfig(
+        "{" +
+                " \"displaymanager\": \"Google\"," +
+                " \"displaymanagerver\": \"" + MobileAds.getVersion() + "\"," +
+                " \"ext\": {" +
+                "   \"myext\": {" +
+                "    \"test\": 1" +
+                "   }" +
+                " }" +
+        "}"
+);
+```
+
+The parameter passed to `TargetingParams.setGlobalOrtbConfig()` will be merged into all SDK's bid requests on the global level. For instance, the above example will add the `$.ext.myext.test` parameter and change the `displaymanager` and `displaymanagerver` parameters in each request. 
+
+To invalidate the global config, just set the empty string: 
 
-While there are many specific methods for adding data to the request detailed in
-this document, OpenRTB is big and it moves quickly. To cover scenarios not already covered by an existing method,
-Prebid SDK Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the [OpenRTB structure](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md) -- it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server.
+``` kotlin
+TargetingParams.setGlobalOrtbConfig("")
+```
 
-There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed.
+The `TargetingParams.setGlobalOrtbConfig()` also allows to **add** impression objects to the request. All objects in the `$.imp[]` array will be added to the request. Note that Ad Unit's `imp` object won't be changed using Global Config. To change the `imp` config, use the `setImpORTBConfig()` method of a particular Ad Unit. See the Ad Unit documentation for the details. 
 
-Here's how to specify cross-impression data:
+Pay attention that there are certain protected fields such as `regs`, `device`, `geo`, `ext.gdpr`, `ext.us_privacy`, and `ext.consent` which cannot be changed using the `setGlobalOrtbConfig()` method.
 
-```kotlin
-//global invocation
-adUnitConfiguration?.ortbConfig = "{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}"
-```
+- App and User first party data should use the [functions defined for those purposes](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data)
+- See the [Prebid Server auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#prebid-server-ortb2-extension-summary) reference for more information about how it will process incoming fields.
 
-To merge impression-level data, use the `adUnit` object:
+### Deprecated 
+{:.no_toc}
 
-```kotlin
+The Prebid Mobile SDK v2.2.1 contains the deprecated method to set the impression level RTB config: 
+
+``` swift
 //ad unit / impression-level
-adUnit?.ortbConfig = "{\"ext\":{\"gpid\":\"abc123\"}}"
+adUnit.setOrtbConfig("{\"ext\":{\"gpid\":\"abc123"}}\")
 ```
 
-Notes:
-
-- App and User first party data should use the [functions defined for those purposes](/prebid-mobile/pbm-api/android/pbm-targeting-android.html#first-party-data)
-- See the [Prebid Server auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#prebid-server-ortb2-extension-summary) reference for more information about how it will process incoming fields.
+This method has implementation issues and was deprecated in v2.4.0. If you use this method, we strongly recommend migrating to the new `setImpORTBConfig()` method since this one will be removed entirely in SDK version 3.0.
 
 ## Further Reading
 

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

@@ -509,32 +509,52 @@ All of the targeting class methods have been mentioned above in the context of F
 
 ## Arbitrary OpenRTB
 
-(requires SDK v2.2.1)
+(requires SDK v2.4.0)
+
+Prebid SDK allows the customization of the OpenRTB request on the global level using `setGlobalORTBConfig()` function: 
+
+``` swift
+let globalORTB = """
+{
+    "ext": {
+        "myext": {
+            "test": 1
+        }
+    },
+    "displaymanager": "Google",
+    "displaymanagerver": "\(GADGetStringFromVersionNumber(GADMobileAds.sharedInstance().versionNumber))"
+}
+"""
+
+Targeting.shared.setGlobalORTBConfig(globalORTB)
+```
+
+The parameter passed to `Targeting.shared.setGlobalORTBConfig()` will be merged into all SDK's bid requests on the global level. For instance, the above example will add the `$.ext.myext.test` parameter and change the `displaymanager` and `displaymanagerver` parameters in each request. 
 
-While there are many specific methods for adding data to the request detailed in
-this document, OpenRTB is big and it moves quickly. To cover scenarios not already covered by an existing method,
-Prebid SDK Provides a way for app publishers to customize most ORTB fields in the partial bid request that Prebid Mobile sends to the Prebid Server. The customization comes in the form of the ortbConfig parameter that takes a JSON String as input. The JSON string must follow the [OpenRTB structure](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md) -- it will be merged with the current JSON of the bid request. If you choose to input extra data using the ortbConfig parameter, please extensively test your requests sent to Prebid Server.
+To invalidate the global config, just set the empty string: 
 
-There are certain protected fields such as regs, device, geo, ext.gdpr, ext.us_privacy, and ext.consent which cannot be changed.
+``` swift
+Targeting.shared.setGlobalORTBConfig("")
+```
 
-Here's how to specify cross-impression data:
+The `Targeting.shared.setGlobalORTBConfig()` also allows to **add** impression objects to the request. All objects in the `$.imp[]` array will be added to the request. Note that Ad Unit's `imp` object won't be changed using Global Config. To change the `imp` config, use the `setImpORTBConfig()` method of a particular Ad Unit. See the Ad Unit documentation for the details. 
 
-```swift
-//global invocation
-adUnitConfig.setOrtbConfig("{\"ext\":{\"prebid\":{\"debug\":1,\"trace\":\"verbose\"}}}")
-```
+Pay attention that there are certain protected fields such as `regs`, `device`, `geo`, `ext.gdpr`, `ext.us_privacy`, and `ext.consent` which cannot be changed using the `setGlobalORTBConfig()` method.
 
-To merge impression-level data, use the `adUnit` object:
+- App and User first party data should use the [functions defined for those purposes](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data)
+- See the [Prebid Server auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#prebid-server-ortb2-extension-summary) reference for more information about how it will process incoming fields.
 
-```swift
+### Deprecated 
+{:.no_toc}
+
+The Prebid Mobile SDK v2.2.1 contains the deprecated method to set the impression level RTB config: 
+
+``` swift
 //ad unit / impression-level
 adUnit.setOrtbConfig("{\"ext\":{\"gpid\":\"abc123"}}\")
 ```
 
-Notes:
-
-- App and User first party data should use the [functions defined for those purposes](/prebid-mobile/pbm-api/ios/pbm-targeting-ios.html#first-party-data)
-- See the [Prebid Server auction endpoint](/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#prebid-server-ortb2-extension-summary) reference for more information about how it will process incoming fields.
+This method has implementation issues and was deprecated in v2.4.0. If you use this method, we strongly recommend migrating to the new `setImpORTBConfig()` method since this one will be removed entirely in SDK version 3.0.
 
 ## Further Reading