Mobile: Rewarded Ad Unit Enhancements

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

@@ -0,0 +1,68 @@
+##### 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 using stored impression-level stored request and the [passthrough](https://docs.prebid.org/prebid-server/endpoints/openrtb2/pbs-endpoint-auction.html#request-passthrough) feature of Prebid Server. 
+
+Prebid SDK will search for a particular `rwdd` object in `ext.prebid.passthrough` of bid response to configure the behavior 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
+{
+  "ext": {
+    "prebid": {
+      "storedauctionresponse": {
+        "id": "prebid-response-video-rewarded-endcard"
+      },
+      "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 @@
 
 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 @@
 }
 ```
 
-#### 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 @@
 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,8 @@
 {% 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 +257,7 @@
 
 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 +267,12 @@
 
 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 +283,23 @@
 }
 ```
 
-### 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 +313,7 @@
 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).
 
 ## Additional Ad Unit Configuration
 

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

@@ -161,9 +161,11 @@
 
 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 @@
 
 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
+    }
+}
+```
+
 ## Further Reading
 
 - [Prebid Mobile Overview](/prebid-mobile/prebid-mobile)

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

@@ -168,9 +168,11 @@
 
 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
 
-Integration example:
+{% include mobile/rewarded-server-side-configuration.md %}
+
+##### Integration example
 
 ```swift
 // 1. Create GADRequest
@@ -210,27 +212,27 @@
 
 To be notified when a user earns a reward follow the [AdMob intructions](https://developers.google.com/admob/ios/rewarded#show_the_ad).
 
-#### Step 1: Create GADRequest
+##### Step 1: Create GADRequest
 {:.no_toc}
 
 This step is the same as for the original [AdMob integration](https://developers.google.com/admob/ios/rewarded). You don't have to make any modifications here.
 
-#### Step 2: Create MediationRewardedAdUnit
+##### Step 2: Create MediationRewardedAdUnit
 {:.no_toc}
 
 The `AdMobMediationRewardedUtils` is a helper class, which performs certain utilty work for the `MediationRewardedAdUnit`, like passing the targeting keywords to the adapters.
 
-#### Step 3: Create MediationInterstitialAdUnit
+##### Step 3: Create MediationInterstitialAdUnit
 {:.no_toc}
 
 The `MediationRewardedAdUnit` 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 a Prebid server and provides a result in a completion handler.
 
-#### Step 5: Make an Ad Request
+##### Step 5: Make an Ad Request
 {:.no_toc}
 
 Make a regular AdMob's ad request. Everything else will be handled by GMA SDK and prebid adapters.