Mobile: Rewarded Ad Unit Enhancements

_includes/mobile/rewarded-server-side-configuration.md

@@ -0,0 +1,72 @@
+##### Server-side Rewarded Ad Unit Configuration
+
+The Rewarded Ad Unit assumes special behavior that should be configurable by the platform or publisher according to the application or ad experience guides.  
+
+Configuration of rewarded ad unit can be done by defining the Prebid Server [passthrough extension](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#request-passthrough) or by using a stored impression-level request on the server.
+
+Prebid SDK will search for a particular `rwdd` object in `$.seatbid.bid.ext.prebid.passthrough` of bid response to configure the behavior and rendering of the Rewarded Ad Unit. The following table describes the structure and usage purpose of `rwdd` configuration parameters.  
+
+{: .table .table-bordered .table-striped }
+| Attribute | Type | Description | Example |  
+|-----------|------|-------------|---------|
+| `reward`             | object <br> (optional)   | Metadata provided by the publisher to describe the reward.                                                             |<code>{<br>&nbsp;"type": "SuperDollars",<br>&nbsp;"count": 10<br>}</code> | 
+| `reward.type`        | string   | Type of the reward in the app's coins. | `"SuperDollars"` | 
+| `reward.count`       | integer  | Amount of coins. | `10` | 
+| `reward.ext`         | object   | For future extensions. | <code>{<br>&nbsp;"ext": {}<br>}</code> | 
+| `completion`         | object <br> (optional)   | Describes the condition when the SDK should send a signal to the app that the user has earned the reward. |<code>{<br>&nbsp;"video": {<br>&nbsp;&nbsp;"endcard": {<br>&nbsp;&nbsp;&nbsp;"time": 5 <br>&nbsp;&nbsp;&nbsp;} <br>&nbsp;&nbsp;} <br>}</code> | 
+| `completion.banner`  | object   | Details for banner ad completion. |<code>{<br>&nbsp;"time": 5,<br>&nbsp;"event": "custom_event_url" <br>}</code> | 
+| `completion.banner.time`   | integer  | Period of time the banner ad is on screen. | `5` | 
+| `completion.banner.event`  | string   | URL with custom schema sent by the creative to indicate that the user did earn a reward. | `"rwdd://userDidEarnReward"` | 
+| `completion.video`   | object   | Details for video ad completion. |<code>{<br>&nbsp;"endcard": {<br>&nbsp;&nbsp;"time": 5 <br>&nbsp;} <br>}</code> | 
+| `completion.video.time`    | integer  | Period of time the video ad is on screen. | `10` | 
+| `completion.video.playbackevent` | string   | The playback event stage in the video. | `"start"`, `"firstquartile"`, `"midpoint"`, `"thirdquartile"`, `"complete"` | 
+| `completion.video.endcard` | object   | Properties for the end card. |<code>{<br>&nbsp;"time": 5 <br>}</code> | 
+| `completion.video.endcard.time` | integer  | Period of time the end card is on screen. | `5` | 
+| `completion.video.endcard.event` | string   | URL with custom schema sent by the creative for end card. | `"rwdd://userDidEarnReward"` | 
+| `close`              | object <br> (optional)   | Describes the ad close behavior after the reward is earned. |<code>{<br>&nbsp;"postrewardtime": 3,<br>&nbsp;"action": "autoclose"<br>}</code> | 
+| `close.postrewardtime` | integer  | Time interval (seconds) after reward event when SDK should close interstitial. | `3` | 
+| `close.action`       | string   | Action SDK should make: `"autoclose"` (close interstitial) or `"closebutton"` (show close button) | `"autoclose"` | 
+
+
+An example of an impression-level stored request:
+
+```json
+{
+  "video": {
+    "h": 480,
+    "w": 320,
+    "mimes": ["video/mp4"],
+    "linearity": 1,
+    "placement": 2,
+    "playbackmethod": [2]
+  },
+  "ext": {
+    "prebid": {
+      "passthrough": [
+        {
+          "type": "prebidmobilesdk",
+          "rwdd": {
+            "reward": {
+              "type": "SuperDollars",
+              "count": 10
+            },
+            "completion": {
+              "video": {
+                "endcard": {
+                  "time": 5
+                }
+              }
+            },
+            "close": {
+              "postrewardtime": 3,
+              "action": "autoclose"
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+More details about the SDK behavior according to the `rwdd` configuration you can find in the [GitHub Proposal](https://github.com/prebid/prebid-mobile-ios/pull/1058).

prebid-mobile/modules/rendering/android-sdk-integration-admob.md

@@ -186,9 +186,11 @@ Now you should just make a regular AdMob's ad request. Evetything else will be h
 
 Once you receive the ad it will be ready for display. You can show interstitial right in the listener or later according to the app logic.
 
-### Rewarded Video
+### Rewarded 
 
-Integration example:
+{% include mobile/rewarded-server-side-configuration.md %}
+
+#### Integration example
 
 ```kotlin
 // 1. Create AsRequest
@@ -230,32 +232,32 @@ adUnit?.fetchDemand { result ->
 }
 ```
 
-#### Step 1: Create AdRequest
+##### Step 1: Create AdRequest
 {:.no_toc}
 
 This step is the same as for the original [AdMob integration](https://developers.google.com/admob/android/rewarded). You don't have to make any modifications here.
 
-#### Step 2: Create AdMobRewardedMediationUtils
+##### Step 2: Create AdMobRewardedMediationUtils
 {:.no_toc}
 
 The `AdMobRewardedMediationUtils` is a helper class, which performs certain utilty work for the `MediationInterstitialAdUnit`, like passing the targeting keywords to adapters.
 
-#### Step 3: Create MediationRewardedVideoAdUnit
+##### Step 3: Create MediationRewardedVideoAdUnit
 {:.no_toc}
 
 The `MediationRewardedVideoAdUnit` is part of the prebid mediation API. This class is responsible for making bid request and managing the winning bid.
 
-#### Step 4: Make a bid request
+##### Step 4: Make a bid request
 {:.no_toc}
 
 The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler.
 
-#### Step 5: Make an ad request
+##### Step 5: Make an ad request
 {:.no_toc}
 
 Now you should just make a regular AdMob's ad request. Evetything else will be handled by GMA SDK and prebid adapters.
 
-#### Step 6: Display an ad
+##### Step 6: Display an ad
 {:.no_toc}
 
 Once you receive the ad it will be ready for display. You can show interstitial right in the listener or later according to the app logic.

prebid-mobile/modules/rendering/android-sdk-integration-gam.md

@@ -215,9 +215,13 @@ Integration:
 4. Remove the original `InterstitialAdUnit`.
 5. Follow the instructions to integrate [Interstitial API](#interstitials).  
 
-### Rewarded Video
+### Rewarded
 
-To display a Rewarded Ad follow these steps:
+{% include mobile/rewarded-server-side-configuration.md %}
+
+#### Integration example
+
+Displaying the **Rewarded Ad** is the same as displaying an Interstitial Ad, but it adds ability to handle reward. To display a Rewarded Ad follow these steps:
 
 ```kotlin
 // 1. Create a rewarded custom event handler for GAM ad server.
@@ -243,21 +247,7 @@ Pay attention that the `loadAd()` should be called on the main thread.
 {% endcapture %}
 {% include /alerts/alert_warning.html content=warning_note %}
 
-Displaying the **Rewarded Ad** is the same as displaying an Interstitial Ad. The type of ad can be customized to:
-
-Be notified when user earns a reward - implement `RewardedAdUnitListener` interface:
-
-```kotlin
- fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit)
-```
-
-When the actual reward object is stored in the `RewardedAdUnit`:
-
-```kotlin
-val reward = rewardedAdUnit.getUserReward()
-```
-
-#### Step 1: Create Event Handler
+##### Step 1: Create Event Handler
 {:.no_toc}
 
 GAM's event handlers are special containers that wrap the GAM Ad Views and help to manage collaboration between GAM and Prebid views.
@@ -266,7 +256,7 @@ GAM's event handlers are special containers that wrap the GAM Ad Views and help
 
 To create an event handler you should provide a GAM Ad Unit.
 
-#### Step 2: Create Rewarded Ad Unit
+##### Step 2: Create Rewarded Ad Unit
 {:.no_toc}
 
 **RewardedAdUnit** - is an object that will load and display the particular ad. To create it you should provide
@@ -276,12 +266,12 @@ To create an event handler you should provide a GAM Ad Unit.
 
 You can also assign the listener for processing ad events.
 
-#### Step 3: Load the Ad
+##### Step 3: Load the Ad
 {:.no_toc}
 
 Call the `loadAd()` method to make a bid request. The ad unit will load an ad and will wait for explicit instructions to display the Rewarded Ad.
 
-#### Step 4: Display the Ad when it is ready
+##### Step 4: Display the Ad when it is ready
 {:.no_toc}
 
 The most convenient way to determine if the ad is ready for displaying is to listen for the listener method:
@@ -292,7 +282,23 @@ override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) {
 }
 ```
 
-### Migrating rewarded video from a Bidding-Only integration
+##### Step 5: Handle a reward
+{:.no_toc}
+
+Handle earning the reward in the appropriate method. Important: a reward can be null.
+
+```kotlin
+override fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit?, reward: Reward?) {
+    if (reward != null) {
+        val rewardType = reward.type
+        val rewardCount = reward.count
+        val rewardExt = reward.ext
+        // Process the reward
+    }
+}
+```
+
+#### Migrating rewarded video from a Bidding-Only integration
 {:.no_toc}
 
 GAM setup:
@@ -306,7 +312,7 @@ Integration:
 1. Replace the `RewardedAd` with `RewardedAdUnit`.
 2. Implement the interface for `RewardedAdUnitListener`.
 3. Remove the original `RewardedVideoAdUnit`.
-4. Follow the instructions to integrate [Rewarded API](#rewarded-video).
+4. Follow the instructions to integrate [Rewarded API](#rewarded).
 
 ## Additional Ad Unit Configuration
 

prebid-mobile/modules/rendering/android-sdk-integration-max.md

@@ -161,9 +161,11 @@ Now you should make a regular MAX's ad request. Everything else will be handled
 
 Once you receive the ad it will be ready for display. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/android/getting-started/interstitials#showing-an-interstitial-ad) about how to do it. 
 
-### Rewarded Video
+### Rewarded 
 
-Integration example:
+{% include mobile/rewarded-server-side-configuration.md %}
+
+#### Integration example
 
 ```kotlin
 // 1. Get an instance of MaxRewardedAd
@@ -192,35 +194,36 @@ The way of displaying the rewarded ad is the same as for the Interstitial Ad.
 
 To be notified when user earns a reward follow the [MAX intructions](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads#accessing-the-amount-and-currency-for-a-rewarded-ad).
 
-#### Step 1: Get an instance of MaxRewardedAd
+##### Step 1: Get an instance of MaxRewardedAd
 {:.no_toc}
 
 This step is totally the same as for original [MAX integration](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads). You don't have to make any modifications here.
 
-#### Step 2: Create MaxMediationRewardedUtils
+##### Step 2: Create MaxMediationRewardedUtils
 {:.no_toc}
 
 The `MaxMediationRewardedUtils` is a helper class, which performs certain utilty work for the `MediationRewardedVideoAdUnit`, like passing the targeting keywords to the adapters.
 
-#### Step 3: Create MediationRewardedVideoAdUnit
+##### Step 3: Create MediationRewardedVideoAdUnit
 {:.no_toc}
 
 The `MediationRewardeVideoAdUnit` is part of the prebid mediation API. This class is responsible for making a bid request and providing a winning bid and targeting keywords to the adapters.  
 
-#### Step 4: Make bid request
+##### Step 4: Make bid request
 {:.no_toc}
 
 The `fetchDemand` method makes a bid request to the prebid server and provides a result in a completion handler.
 
-#### Step 5: Make an Ad Reuest
+##### Step 5: Make an Ad Reuest
 {:.no_toc}
 
 Now you should make a regular MAX's ad request. Everything else will be handled by GMA SDK and prebid adapters.
 
-#### Steps 6: Display an ad
+##### Steps 6: Display an ad
 {:.no_toc}
 
 Once the rewarded ad is received you can display it. Folow the [MAX instructions](https://dash.applovin.com/documentation/mediation/android/getting-started/rewarded-ads#showing-a-rewarded-ad) for the details. 
+
 ### Native Ads
 
 Integration example:

prebid-mobile/modules/rendering/android-sdk-integration-pb.md

@@ -192,9 +192,11 @@ override fun onAdLoaded(interstitialAdUnit: InterstitialAdUnit) {
 }
 ```
 
-#### Rewarded Video
+#### Rewarded
 
-Integration example:
+{% include mobile/rewarded-server-side-configuration.md %}
+
+##### Integration example
 
 ``` kotlin
 // 1. Create an Ad Unit
@@ -215,19 +217,19 @@ Pay attention that the `loadAd()` should be called on the main thread.
 {% endcapture %}
 {% include /alerts/alert_warning.html content=warning_note %}
 
-##### Step 1: Create a Rewarded Ad Unit
+###### Step 1: Create a Rewarded Ad Unit
 {:.no_toc}
 
 Create the `RewardedAdUnit` object with parameters:
 
 - `adUnitId` - an ID of Stored Impression on the Prebid server.
 
-##### Step 2: Load the Ad
+###### Step 2: Load the Ad
 {:.no_toc}
 
 Call the `loadAd()` to make a bid request.
 
-##### Step 3: Show the Ad when it is ready
+###### Step 3: Show the Ad when it is ready
 {:.no_toc}
 
 Wait until the ad is loaded and present it to the user in any suitable time.
@@ -238,6 +240,22 @@ override fun onAdLoaded(rewardedAdUnit: RewardedAdUnit) {
 }
 ```
 
+##### Step 4: Handle a reward
+{:.no_toc}
+
+Handle earning a reward in the appropriate method. Important: a reward can be null.
+
+```kotlin
+override fun onUserEarnedReward(rewardedAdUnit: RewardedAdUnit?, reward: Reward?) {
+    if (reward != null) {
+        val rewardType = reward.type
+        val rewardCount = reward.count
+        val rewardExt = reward.ext
+        // Process the reward
+    }
+}
+```
+
 ## Additional Ad Unit Configuration
 
 {% include mobile/rendering-adunit-config-android.md %}

prebid-mobile/modules/rendering/ios-sdk-integration-admob.md

@@ -235,7 +235,9 @@ Make a regular AdMob's ad request. Everything else will be handled by GMA SDK an
 
 Once you receive the ad it will be ready for display. Follow the [AdMob instructions](https://developers.google.com/admob/ios/interstitial#swift) for displaying an ad.
 
-### Rewarded Video
+### Rewarded
+
+{% include mobile/rewarded-server-side-configuration.md %}
 
 **Integration example(Swift)**: