Skip to main content

Rewarded Ads

Ad Request​

Placement​

Create a RewardedRequest.Builder instance, set placement id and other parameters, if applicable.

val rewardedRequestBuilder = RewardedRequest.Builder()
        .setTargetingParams(...) // Set TargetingParams instance
        .setPriceFloorParams(...) // Set price floor parameters
        .setLoadingTimeOut(...) // Set loading timeout in milliseconds
        .setPlacementId(...) // Set placement id

General Request​

Set the RewardedRequest.AdRequestListener instance to theRewardedRequest.Builder instance.

rewardedRequestBuilder.setListener(object : RewardedRequest.AdRequestListener {
    
    override fun onRequestSuccess(request: RewardedRequest,
                                  auctionResult: AuctionResult) {
        // Called when RewardedRequest was requested successfully
    }

    override fun onRequestFailed(request: RewardedRequest,
                                 error: BMError) {
        // Called when RewardedRequest request failed
    }

    override fun onRequestExpired(request: RewardedRequest) {
        // Called when RewardedRequest expired
    }
})
info

AdRequestListener callbacks are delivered on the background thread, not the main one.

When all the necessary parameters are set, call build on the RewardedRequest.Builder instance:

val rewardedRequest = rewardedRequestBuilder.build()
info

You need to keep reference to RewardedRequest before calling RewardedRequest#request, otherwise, it is possible it will be cleared by Garbage Collector and callbacks won’t be triggered.

Client Bidding Request​

Bid Token​

With S2S integration, you will need a BidToken that you need to transfer in the request.

Define AdPlacementConfig:

val adPlacementConfig = AdPlacementConfig.Builder(AdsFormat)
  .withPlacementId(...) // Set placement id
  .build()

To get a BidToken, you can use one of 2 methods:

// Must be run on background thread
val bidToken = BidMachine.getBidToken(Context, AdPlacementConfig)

or

BidMachine.getBidToken(Context, AdPlacementConfig) { bidToken ->
    // The BidToken will be returned on a background thread
}

Bid Payload​

After completing the server-side auction, you will receive a Base64-encoded payload string, which must be passed as a parameter to the RewardedRequest.Builder:

rewardedRequestBuilder.setBidPayload(String?)

When all the necessary parameters are set, call build on the RewardedRequest.Builder instance:

val rewardedRequest = rewardedRequestBuilder.build()
info

You need to keep reference to RewardedRequest before calling RewardedRequest#request, otherwise, it is possible it will be cleared by Garbage Collector and callbacks won’t be triggered.

Ad Display​

Prepare the Ad Request object​

When you need to request an ad and get an AuctionResult, call request on the RewardedRequest instance.

rewardedRequest.request(...)
info

When you made an in-house meditation and you decided that an advertisement from BidMachine will be shown - call rewardedRequest.notifyMediationWin, if BidMachine lost in mediation - call rewardedRequest.notifyMediationLoss

Destroy the RewardedRequest instance if you don't need it anymore.

rewardedRequest.destroy()
caution

Don't destroy the RewardedRequest instance, if it will be used for load the RewardedAd instance or if the RewardedAd instance loaded with the RewardedRequest instance has not been shown yet. Otherwise, ad will not work correctly, which can affect a lower display rate, fill rate, rendering errors, and as a result - lower revenue.

Define Ad Listener​

Before execute load on the RewardedAd instance set the RewardedListener instance:

val rewardedAd = RewardedAd(...)
rewardedAd.setListener(object : RewardedListener {
    
    override fun onAdLoaded(ad: RewardedAd) {
        // Called when Ad was loaded and ready to be displayed
    }

    override fun onAdLoadFailed(ad: RewardedAd,
                                error: BMError) {
        // Called when Ad failed to load
    }

    override fun onAdImpression(ad: RewardedAd) {
        // Called when Ad Impression has been tracked
    }
    
    override fun onAdShowFailed(ad: RewardedAd,
                                error: BMError) {
        // Called when Ad show failed
    }
    
    override fun onAdClicked(ad: RewardedAd) {
        // Called when Ad has been clicked
    }
  
    override fun onAdRewarded(ad: RewardedAd) {
        // Called when Rewarded Ad was completed (e.g.: the video has been played to the end).
        // You can use this event to reward the user
    }

    override fun onAdClosed(ad: RewardedAd,
                            finished: Boolean) {
        // Called when Ad was closed (e.g - user clicked the close button)
        // finished indicates if the ad was finished (e.g - video playing completed)
    }

    override fun onAdExpired(ad: RewardedAd) {
        // Called when Ad expired
    }
  
})
rewardedAd.load(rewardedRequest)

Loading and presenting rewarded ads​

Make sure that the RewardedRequest instance have AuctionResult. It's mean ads requested successfully.

rewardedRequest.auctionResult != null

Use onAdLoaded callback to determine the possibility of displaying

Before displaying, check if the RewardedAd instance can be displayed:

rewardedAd.canShow()

To display the RewardedAd instance, you just need to execute show.

rewardedAd.show()

After ad was successful shown and no longer needed, it can be destroyed.

rewardedAd.destroy()
info

You can find code examples written in Java and Kotlin: Github Rewarded