Prebid mobile release 2 1 0 (#3820)

* doc: update docs for ios - original api - targeting

* doc: actualization for "targeting" page in the Rendering sections

* update android docs for targeting pages

* updates for the ad experience controls

* update android ad experience controls page

* fix TOC

* Update android-sdk-customization-controls.md

* Update android-sdk-customization-controls.md

* Update android-sdk-parameters.md

* Update ios-sdk-customization-controls.md

* Update ios-sdk-customization-controls.md

* Update android-sdk-customization-controls.md

* Update ios-sdk-parameters.md

Co-authored-by: Yuriy Velichko <[email protected]>
Co-authored-by: Valentin Petrovych <[email protected]>
Co-authored-by: MartianTribe <[email protected]>

prebid-mobile/modules/rendering/android-sdk-customization-controls.md

@@ -8,55 +8,159 @@ sidebarType: 2
 ---
 
 # Ad Experience Controls
+{:.no_toc}
 
 Prebid SDK provides an API way to customize its behaviour. 
 
-> NOTE: In the nearest future the Server Side Configuration will be supported as well. Follow this [feature request](https://github.com/prebid/prebid-server/issues/2186) for the details. 
+> NOTE: Planned future enhancements will support Server Side Configuration. Follow this [feature request](https://github.com/prebid/prebid-server/issues/2186) for the details. 
+
+* TOC
+{:toc}
 
 
 ## Rendering Controls
 
-The following properties allow to customize the rendering of Video Interstitial Ads.
+
+The following properties enable rendering customization of Video Interstitial Ads.
 
 ### Max Video Duration
 
-The `maxVideoDuration` indicates the maximum available playback time in seconds.
-If the value in the **Duration** tag is bigger than the given value SDK will fail to load ad, providing a respective error message.
+This control sets the maximum available video duration in seconds. Prebid SDK sends the value of this property in the  `imp.video.maxduration` object of the bid request. If the value in the received VAST tag `<Duration>` is larger than the given number the SDK will not load the media file, the ad load will fail and an error message will be generated.
+
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         | `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setMaxVideoDuration(seconds)`|
+|**Server Property**    | `maxvideoduration` *(pending for PBS implementation)*|
+|**Default Value**     | `3600 seconds`|
 
 ### Application Muted
 
-The `isMuted` property indicates whether the ad should run playback with sound or not.
-Default value - **false**.
+This control enables playback to toggle sound on or off.  
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         | `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setIsMuted(true)`|
+|**Server Property**    | `ismuted` *(pending for PBS implementation)*|
+|**Default Value**     | `false`|
 
 ### Close Button Area
 
-The `closeButtonArea` property indicates the percent of device screen which the close button should occupy. The possible values are from **0** to **1**.
+This control sets the percent of device screen which the close button should occupy.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         | `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setCloseButtonArea(factor) `|
+|**Server Property**    | `closebuttonarea` *(pending for PBS implementation)*|
+|**Allowed Values**     | `0..1`|
+|**Default Size**       | `70dp`|
+
+Customization Example
+
+{: .table .table-bordered .table-striped }
+
+|**Default**|**Custom**|
+|![Close Button Area - Default](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-close-button-area-default.jpg){:width="250px"}|![Close Button Area - Custom](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-close-button-area-custom.jpg){:width="250px"}|
+
 
 ### Close Button Position
 
-The `closeButtonPosition` property indicates the position of the close button on the screen. The possible values are **Position.BOTTOM_LEFT** and **Position.TOP_RIGHT**. The default value is **Position.TOP_RIGHT**.
+This control sets the position of the close button on the screen.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setCloseButtonPosition(Position.TOP_LEFT)`|
+|**Server Property**    | `closebuttonposition` *(pending for PBS implementation)*|
+|**Allowed Values**     | `Position.TOP_LEFT, Position.TOP_RIGHT`|
+|**Default Value**      | `Position.TOP_RIGHT`|
 
-The example: 
 
-![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-android-close-button-possition-top-left.png){:width="250px"}
+Customization Example
+
+{: .table .table-bordered .table-striped }
+
+|**Default**|**Custom**|
+|![Close Button Position - Default](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-close-button-position-default.jpg){:width="250px"}|![Close Button Position - Custom](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-close-button-position-custom.jpg){:width="250px"}|
+
 
 ### Skip Button Area
 
-The `skipButtonArea` property indicates the percent of device screen which the skip button should occupy. The possible values are from **0** to **1**.
+This control sets the percent of device screen which the skip button should occupy.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setSkipButtonArea(factor)`|
+|**Server Property**    | `skipbuttonarea` *(pending for PBS implementation)*|
+|**Allowed Values**     | `0..1`|
+|**Default Value**      | `70dp`|
+
+Customization Example
+
+{: .table .table-bordered .table-striped }
+
+|**Default**|**Custom**|
+|![Close Button Position - Default](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-skip-button-area-default.jpg){:width="250px"}|![Close Button Position - Custom](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-skip-button-area-custom.jpg){:width="250px"}|
+
 
 ### Skip Button Position
 
-The `skipButtonPosition` property indicates the position of the close button on the screen. The possible values are **Position.BOTTOM_LEFT** and **Position.TOP_RIGHT**. The default value is **Position.BOTTOM_LEFT**.
+This control sets the position of the skip button on the screen.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setSkipButtonPosition(Position.TOP_LEFT)`|
+|**Server Property**    | `skipbuttonposition` *(pending for PBS implementation)*|
+|**Allowed Values**     | `Position.TOP_LEFT, Position.TOP_RIGHT`|
+|**Default Value**      | `Position.TOP_RIGHT`|
+
+Customization Example
+
+{: .table .table-bordered .table-striped }
+
+|**Default**|**Custom**|
+|![Close Button Position - Default](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-skip-button-position-default.jpg){:width="250px"}|![Close Button Position - Custom](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-skip-button-position-custom.jpg){:width="250px"}|
+
+### Sound Button
 
-The example: 
+This control toggles the display of the sound/mute button to users.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setIsSoundButtonVisible(true)`|
+|**Server Property**    | *not supported*|
+|**Default Value**      | `false`|
+
+Customization Example
+
+{: .table .table-bordered .table-striped }
+
+|**Custom**|
+|![Close Button Area - Default](/assets/images/prebid-mobile/modules/rendering/ad-experience/android-sound-button.jpg){:width="250px"}|
 
-![Close Button Position - Top Right](/assets/images/prebid-mobile/modules/rendering/ad-experience-android-skip-button-possition-top-left.png){:width="250px"}
 
 ### Skip Delay
 
-The `skipDelay` property indicates the number of seconds which should be passed from the start of playback until the skip or close button should be shown. The default value is **10**.
+This control sets number of seconds which should be passed from the start of playback until the skip or close button should be shown.
+
+{: .table .table-bordered .table-striped }
+
+|**API Object**         `InterstitialAdUnit`, `RewardedAdUnit`, <br />`MediationInterstitialAdUnit`, `MediationRewardedVideoAdUnit` |
+|**Ad Unit Property**   | `adUnit.setSkipDelay(seconds)`|
+|**Server Property**    | `skipdelay` *(pending for PBS implementation)*|
+|**Default Value**      | `10 seconds`|
+
+
+### Customization examples
+
+The code sample:
 
-The code sample: 
 
 ``` kotlin
 adUnit = MediationInterstitialAdUnit(
@@ -71,6 +175,6 @@ adUnit?.setCloseButtonArea(0.1)
 adUnit?.setSkipDelay(5)
 adUnit?.setSkipButtonArea(0.1)
 adUnit?.setSkipButtonPosition(Position.TOP_RIGHT)
-adUnit?.setCloseButtonPosition(Position.BOTTOM_LEFT)
+adUnit?.setCloseButtonPosition(Position.TOP_LEFT)
 ```
 

prebid-mobile/modules/rendering/android-sdk-parameters.md

@@ -9,73 +9,39 @@ sidebarType: 2
 
 # Parameters
 
-The tables below list the methods and properties that the Prebid Rendering API allows to customize.
-The more actual info about the user, the app, and the device you provide the more chances to win an impression.
+The tables below list the methods and properties that the Prebid Rendering API uses for customization.
+The more data about the user, app, and device that can be provided the more chances to win an impression.
 
-Please strictly follow the recommendations in the below tables and provide all ❗ **Required** and **Highly Recommended** values.
+It is advised that you strictly follow the recommendations in the tables below. Any field marked with an ❗is required and recommended. 
 
-
-1. [Targeting](#targeting)
-2. [PrebidRenderingSettings](#prebidrenderingsettings)
+1. [Targeting Params](#targeting)
+2. [SDK Settings](#prebidrenderingsettings)
 
 ## Targeting
 
+You can use `Targeting` to pass ad call request parameters.
+
 {: .table .table-bordered .table-striped }
 
 | **Parameter**              | **Method**                | Description                                                  | Required?|
 | -------------------------- | ------------------------- | ------------------------------------------------------------ | -------- |
-| age                        | `setUserAge`              | Age of the user in years. For example: `35`   | ❗ Highly Recommended  |
-| buyerid                    | `setBuyerId`              | Buyer-specific ID for the user as mapped by the exchange for the buyer. | Optional |
-| crr                        | `setCarrier`              |  Mobile carrier - Defined by the Mobile Country Code (MCC) and Mobile Network Code (MNC), using the format: <MCC>-<MNC>. For example: `"310-410"` | Optional |
-| customdata                 | `setUserCustomData`       | Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional |
-| dma                        | `setDma`                  | A designated market are. For US locations, indicates the end-user's Designated Market Area. For example: dma=803. | Optional |
-| ext                        | `setUserExt`              | Placeholder for exchange-specific extensions to OpenRTB. | Optional |
-| gen                        | `setUserGender`           | The gender of the user (Male, Female, Other, Unknown). For example: `Gender.FEMALE`  | ❗ Highly Recommended |
-| inc                        | `setUserAnnualIncomeInUs` | Annual income of the user in US dollars. For example: `55000`| ❗ Highly Recommended  |
-| ip                         | `setDeviceIpAddress`            | The IP address of the carrier gateway. If this is not present, Prebid Rendering retrieves it from the request header. For example: `"192.168.0.1"` | ❗ Highly Recommended |
-| keywords                   | `setUserKeywords`         | Comma separated list of keywords, interests, or intent. | Optional |
-| lat, lon                   | `setUserLatLng`           | Location of the user’s home base defined by a provided longitude and latitude. It's highly recommended to provide Geo data to improve the request.| Optional |
-| publisher                  | `setPublisherName`        | Publisher name (may be aliased at the publisher’s request).| Recommended if available  |
-| url/storeurl               | `setAppStoreMarketUrl`    | The URL for the mobile application in Google Play. That field is required in the request. <br />**For example:**` https://play.google.com/store/apps/details?id=com.outfit7.talkingtom`. | ❗ Required  |
-| xid                        | `setUserId`               | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended  |
+| User Age                        | `setUserAge`              | Age of the user in years. For example: `35`   | ❗ Highly Recommended  |
+| Buyer Id                    | `setBuyerId`              | Buyer-specific ID for the user as mapped by the exchange for the buyer. | Optional |
+| Custom User Data                 | `setUserCustomData`       | Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. | Optional |
+| User Extensions                        | `setUserExt`              | Placeholder for exchange-specific extensions to OpenRTB. | Optional |
+| User Gender                        | `setGender`           | The gender of the user (Male, Female, Other, Unknown). For example: `Gender.FEMALE`  | ❗ Highly Recommended |
+| Keywords                   | `addUserKeywords`         | Comma separated list of keywords, interests, or intent. | Optional |
+| Lat, Lon                   | `setUserLatLng`           | Location of the user’s home base defined by a provided longitude and latitude. It's highly recommended to provide Geo data to improve the request.| Optional |
+| Publisher Name                  | `setPublisherName`        | Publisher name (may be aliased at the publisher’s request).| Recommended if available  |
+| Store Url               | `setStoreUrl`    | The URL for the mobile application in Google Play. That field is required in the request. <br />**For example:**` https://play.google.com/store/apps/details?id=com.outfit7.talkingtom`. | ❗ Required  |
+| User ID                        | `setUserId`               | ID of the user within the app. For example: `"24601"` | ❗ Highly Recommended  |
 
-## How to set user parameters
 
-You can use `Targeting` to pass ad call request parameters.
+Example:
 
 ``` java
 // Set user parameters to enrich ad request data.
 // Please see Targeting for the userKeys and the APIs available.
-Targeting.setUserKeywords("socialNetworking");
-Targeting.setUserAge(18);
-Targeting.setUserAnnualIncomeInUs(50000);
-
-// Set parameters.
-// Targeting.setCustomParameters(Hashtable<String, String> params)
-// Targeting.setParameters(Hashtable<String, String> params)
-// clear parameters
-// Targeting.clearParameters()
-// Targeting.clearParameter(String key)
-```
-
-## Custom key-value parameters
-
-You can submit values through `Targeting` for the extended (`c.xxx`) ad-call
-parameters.
-
-{: .table .table-bordered .table-striped }
-
-| **Parameter**           | **Method**          | **Description**                                              |
-| ----------------------- | ------------------- | ------------------------------------------------------------ |
-| custom<br />parameter   | setCustomParameter  | A custom user parameter auto-prepended with c..<br />You should provide the plain name of the parameter, such as xxx, which will be changed to c.xxx when sent. |
-| custom <br />parameters | setCustomParameters | Custom user parameters, which consist of a dictionary of name-value parameter pairs, where each param name will be automatically prepended with c.. |
-
-## PrebidRenderingSettings
-
-{: .table .table-bordered .table-striped }
-
-| **Field**               | **Description**                                              | **Default** |
-| ----------------------- | ------------------------------------------------------------ | ----------- |
-| defaultAutoRefreshDelay | Controls the initial value of `autoRefreshDelay` for all newly created BannerAdViews in seconds. | 60          |
-| logLevel                | Controls the type of messages of the internal logger. Options are:<br />- DEBUG - this is the noisiest level.<br />- ERROR<br />- WARN<br />- NONE | NONE        |
-| sendMRAIDSupportParams  | If `true`, the SDK sends "`af=3,5`", indicating support for MRAID. | true        |
+TargetingParams.addUserKeyword("socialNetworking");
+TargetingParams.setUserAge(18); 
+```        |