Rewarded Ad Unit Enhancements

[teqblaze-yurii]

The current implementation of the RewardedAdUnit is limited by the behavior of the general-purpose Interstitial Ad and doesn’t allow configuring either the Reward object or the UX, which is critical for this ad format.

This proposal describes how the Rewarded Ad Unit should work according to the industry and publishers’ expectations and what changes for the RewardedAdUnit class will make it more usable and publisher-oriented.

The Teqblaze team is already working on implementing this proposal and will introduce the respective PRs soon.

The proposed changes are based on the market research and Teqblaze’s implementation of the Rewarded Ad Unit. They don’t break the current behavior of RewardedAdUnit but extend it.

The Concept of Rewarded Ads

The mechanic of the rewarded ad has two distinct features:

• Special displaying properties that don't allow users to skip the ad.
• Providing a Reward for viewing the ad once the displaying conditions are met. The Reward is a generic object the publisher configures on the server. It is specific to the application or game.

Here is the general workflow of utilizing Rewarded Ad Units in the apps:

1. The Publisher creates a Rewarded Ad Unit on the ad platform with a particular size, format, etc. These configurations are similar to interstitial ad unit configuration. In the case of Prebid, these configurations will be set via stored configs on PBS.
2. The Publisher configures the Reward Object associated with the ad unit. This object contains metadata like reward type and reward count. In the case of Prebid publisher will create a Reward object only in the case of No Ad Server integration. In all other cases, the Reward will be set on the particular ad server. However, the UX configuration should still be set via PBS stored configuration.
3. The SDK makes an ad request for the Rewarded Ad Unit. SDK also adds an imp.rwdd:1 flag to indicate that the request is a subject for the rewarded ad place.
4. The Ad Platform broadcasts the request to the bidders. The imp.rwdd:1 flag signals about the specific ad unit behavior so Demand partners can bid on it as on the premium inventory.
5. The buyer responds with a bid. The bid CPM for the rewarded ad unit might be higher. Because the buyer knows that the rewarded ads are usually non-skippable and can be opt-in, this suggests better user engagement and motivates higher CPMs to be paid.
6. The ad platform attaches the Reward metadata to the bid and sends it back to the application (SDK) in the ad response.
7. The application (SDK) renders the ad and provides the user with the actual in-app Reward converted from the metadata provided in the ad response by the ad platform.

The SDK is in charge of steps 3 and 6 of this flow, which are about:

• Make the bid request to the server
• Manage the specific response by implementing the respective UX.

In the case of Prebid, there is no ad platform. However, publishers can use the Prebid Server to configure the Rewarded Ad Unit utilizing impression-level stored requests and the request passthrough feature. The details will be discussed later in this paper.

SDK Workflow Implementation

The detailed SDK workflow is presented in the following chart:

Most of the functionality depicted in this diagram is already implemented in the Prebid SDK. To fully support the Rewarded ads, we need to fulfill the gaps marked in green:

1. Enrich the ad request with rwdd flag (we will also keep the current flag imp.ext.prebid.is_rewarded_inventory).
2. Pass the ad response and transform the rewarded-specific metadata into an internal model:
   1. Reward object
   2. UI/UX behavior configuration
3. Implement support of behavior rules on displaying the ad:
   1. Completion criteria
   2. Close event
4. Pass the Reward object to the application once the ad's completion criteria are met.

Implementation Details

Step 1: Adjust RewardedAdUnit

Implement specific APIs for RewardedAdUnit. Ensure that the ad request for the RewardedAd contains imp.rwdd: 1 Field as well as imp.ext.prebid.is_rewarded_inventory.

Step 2: Extend Support of Ad Response

We should extend the support of ad response to provide SDK information about

• Rewarded object
• Completion criteria
• Close Trigger

Schema

For this purpose, publishers should use passthrough feature of the Prebid. Publishers should add the special $.imp[].ext.prebid.passthrough.rwdd object into the impression level stored request. SDK will process it in the $.seatbid.bid.ext.prebid.passthrough.rwdd object in the response.

The schema of rwdd Request object:

{  
  "type": "object",  
  "properties": {  
    "reward": {  
      "type": "object",  
      "properties": {  
        "type": {  
          "type": "string"  
        },  
        "count": {  
          "type": "integer"  
        },  
        "ext": {  
          "type": "object"  
        }  
      },  
      "required": \[  
        "type",  
        "count"  
      \]  
    },  
    "completion": {  
      "type": "object",  
      "properties": {  
        "banner": {  
          "type": "object",  
          "properties": {  
            "time": {  
              "type": "integer"  
            },  
            "event": {  
              "type": "string"  
            }  
          }  
        },  
        "video": {  
          "type": "object",  
          "properties": {  
            "time": {  
              "type": "integer"  
            },  
            "playbackevent": {  
              "type": "string"  
            },  
            "endcard": {  
              "type": "object",  
              "properties": {  
                "time": {  
                  "type": "integer"  
                },  
                "event": {  
                  "type": "string"  
                }  
              }  
            }  
          },  
            
        }  
      }  
    },  
    "close": {  
      "type": "object",  
      "properties": {  
        "postrewardtime": {  
          "type": "integer"  
        },  
        "action": {  
          "type": "string"  
        }  
      },  
        
    }  
  },  
  "required": [  
    "reward"  
  ]  
}  

Description of the schema:

• reward - metadata provided by the publisher to describe the Reward
  • type - type of the reward in the app’ coins
  • count - amount of coins
  • ext - for the future extensions
• completion - describes the condition when the SDK should send a signal to the application that the user has earned the reward
  • banner - in the case of the banner ad (and End Card)
    • time - the period of time that the ad is on the screen
    • event - the URL with a custom schema that will be sent by the creative and should be caught by the SDK
  • video - in the case of the video ad (without End Card)
    • time - the period of time that the ad is on the screen
    • playbackevent - the playback part. Available options:
      • start
      • firstquartile
      • midpoint
      • thirdquartile
      • complete
    • endcard - see the banner properties
• close - describes the close behavior. How should the SDK manage the ad when it is encountered as viewed.
  • postrewardtime - the time interval in seconds passed after the reward event when SDK should Close interstitial
  • action - the action that SDK should do
    • autoclose - close the interstitial.
    • closebutton - show the close button.

Example:

{  
  "reward": {  
    "type": "GreenMexican",  
    "count": 3  
  },  
  "completion": {  
    "video": {  
      "endcard": {  
        "time": 7  
      }  
    }  
  },  
  "close": {  
    "postrewardtime": 0,  
    "action": "closebutton"  
  }  
}

Step 3: Changes in the SDK Behavior

The behavior of the RewardedAdUnit is based on two pillars described below: the default settings and configuration received in the bid response.

Default Settings

Property	Value	Description
reward	"type":","count":0	SDK provides an empty object to the applіcation
completion
completion.banner
completion.banner.time	120 second	SDK triggers the completion of the banner rewarded ad after 120 seconds on the screen.
completion.banner.event	n/a
completion.video
completion.video.time	n/a
completion.video.playbackevent	complete	SDK triggers the completion of the banner rewarded ad once the video playback is completed. But only if the ad doesn’t have an end card
completion.video.endcard	n/a	Behaviour is the same as for the same as for banner ad
close
close.postrewardtime	n/a
close.action	closebutton	SDK displays the close button on the interstitial once the completion criteria are met.

Behaviour.

The SDK, in the case of the rewarded ads, behaves due to the combination of the default settings and configuration received in the rwdd object. The rwdd properties have a bigger priority than the default ones, but in some cases, SDK uses the default properties as a fallback.

Property	Value	Behavior
reward	object	SDK doesn’t process the Reward object. SDK only passes it to the application via callback once the completion criteria are met.
completion
completion.banner
completion.banner.time	> 0	SDK waits X seconds and performs on-reward actions.
completion.banner.event	not empty	SDK waits for the “rwdd://userDidEarnReward” event from the ad and performs on-rewarded actions.   Fallback: if no event during the time defined in the default configuration - SDK performs on-reward actions.
completion.video.time	> 0	Applicable to the creative without end card. SDK waits X seconds and performs on-reward actions.
completion.video.playbackevent	not empty	Applicable to the creative without end card. SDK waits for the “X” playback event. and performs on-rewarded actions.
completion.video.endcard	object	SDK waits for the appearance of the end card and applies configuration options of this object. Configuration properties have the same meaning as configuration for the banner ad. Fallback: if the creative have an end card but rwdd configuration does not have this object – SDK uses default banner configuration.
close
close.postrewardtime	> 0	SDK waits X seconds and performs on-close action.
close.action	autoclose	SDK automatically closes the interstitial.
close.action	closebutton	SDK displays the close button on the interstitial.

The following items describe the specific changes in the existing SDK components to follow the Rewarded Ad behavior specification and make UI/UX consistent with this ad format.

Progress Bar (only for video playback)

If the Rewarded ad has a video component, SDK displays the progress bar that counts the time until the user can interact. Depending on the creative kind, the progress bar calculates its length due to the following rules:

• Video without end card
  • time = completion time + postrewardtime
    • completion time - duration of the video before completion criteria are met.
• Video with an end card
  • time = video duration

The progress bar is not displayed on the playable ads or the end cards of the rewarded ads.

Learn More button (video only + no end card)

The rewarded format assumes that the user agrees to watch the whole ad. This means that from the beginning of the playback, until the user earns the Reward, he or she cannot click or close the video.

The SDK shows the Learn More button only when the reward clause is met. The ad experience, in this case, looks like the following chart:

start (playback) ----> completion (event) ---> Learn More (button) ---> postreward (event) ----> close (button)

Note: if the config property completion.video.playbackevent is complete for the video creative without the end card - it is a configuration error.

Completion priority

The following list demonstrates the priority of completion requirements for different kinds of ads:

Ad Kind	event	time	playbackevent	endcard
Banner	1	2	N/A	N/A
Video with End Card	N/A	ignore	ignore	1
Video without End Card	N/A	2	1	ignore

• Ad with end card:
  • endcard
• Ad without end card
  • playbackevent
  • time

Background behavior

The background behavior is the same as that of the interstitial ad. Playback and any other activity are paused until the app is in the background.

Banner event

If the playable ad wants to inform the SDK that the user has earned a reward, the custom URL should be called rwdd://userDidEarnReward. The SDK will intercept the navigation to this URL and perform the on-reward actions.

Only video ad behavior

The ad closes automatically if the video ad duration is less than the completion time + postreward. It even ignores the close action that shows the close button.

Summary

Implementation of the current spec will make RewardedAdUnit more usable and publisher-friendly.

[teqblaze-yurii]

Doc PR: prebid/prebid.github.io#5659