Rewarded Integration Guide

Appnext Android SDK 2.0 supports Rewarded Ads, a full-screen video ad unit that rewards users after they complete watching the video. Rewarded ads are recommended for optional rewards such as coins, hints, extra lives, or premium content.

Step 1. Create a Rewarded Ad

Create a RewardedAd instance using your Appnext placement ID.:

val rewardedAd = RewardedAd("YOUR_PLACEMENT_ID")

Step 2. Load the Rewarded Ad

Call loadAds() before showing the rewarded ad..

rewardedAd.loadAds(context)

With optional load callback:

rewardedAd.loadAds(
    context = context,
    listener = object : RewardedAdLoadCallback {
        override fun onRewardedAdLoaded() {
            // Ad loaded successfully
        }

        override fun onRewardedAdLoadError(error: AppnextError) {
            // Ad failed to load
        }
    }
)

Optional search keyword:

rewardedAd.loadAds(
    context = context,
    searchKeyWord = "games"
)

Step 3. Show the Rewarded Ad

Important: You must call loadAds() before calling showAd(). If showAd() is called before a rewarded ad is loaded, the SDK will trigger onAdError() with an rewarded-not-loaded error.

Only after the ad has been loaded, call showAd().

Reward the user only after onVideoEnded() is called.

rewardedAd.showAd(
    context = context,
    rewardedAdCallbacks = object : RewardedAdCallbacks {
        override fun onAdShown() {
            // Ad shown
        }

        override fun onAdClosed() {
            // Ad closed
        }

        override fun onAdClicked(packageName: String) {
            // Ad clicked
        }

        override fun onAdError(error: AppnextError) {
            // Ad failed to show
        }

        override fun onVideoEnded() {
            // Reward the user here
        }
    }
)

Callbacks

Load Callback

Use RewardedAdLoadCallback to receive load status.

object : RewardedAdLoadCallback {
    override fun onRewardedAdLoaded() {}
    override fun onRewardedAdLoadError(error: AppnextError) {}
}

Ad Callback

Use RewardedAdCallbacks to receive show, close, click, and error events.

object : RewardedAdCallbacks {
    override fun onAdShown() {}
    override fun onAdClosed() {}
    override fun onAdClicked(packageName: String) {}
    override fun onAdError(error: AppnextError) {}
    override fun onVideoEnded() {}
}

Advanced Settings

Configure the ad before calling loadAds.

rewardedAd.setPostBack("YOUR_POSTBACK")
rewardedAd.setCategories("games,tools")
rewardedAd.setSpecificCategories("arcade,puzzle")
rewardedAd.setSearchByPackage("com.example.app")

Available setters:

• setPostBack - String. Postback parameters that will be posted to your server after the user installs an app.
• setCategories - String. Set preferred ad categories, comma-separated.
• setSpecificCategories - String. Set specific ad categories, comma-separated.
• setSearchByPackage - String. Set a specific Android package.

Server-Side Reward Postback

Use RewardedPostback if you want to pass reward information to your server.
Call setRewardedPostback before showing the ad.

rewardedAd.setRewardedPostback(
    RewardedPostback(
        transactionId = "txn_123",
        userId = "user_456",
        rewardType = "coins",
        rewardAmount = "10",
        customParameter = "level_5"
    )
)

At least one RewardedPostback field should be provided for the rewarded postback data to be valid.

(Optional) In-App Header Bidding

Use getECPM() to get the predicted eCPM before loading or showing an ad.

rewardedAd.getECPM(
    context = context,
    onECPMLoaded = object : OnECPMLoaded {
        override fun ecpm(ecpm: ECPM) {
            // eCPM received
        }

        override fun error(error: AppnextError) {
            // eCPM request failed
        }
    }
)

The ecpm object will include the following getters:

• getEcpm - Returns the predicted ECPM value of the banner that is about to be loaded (float type)
• getPpr - Returns the predicted price per request value (ECPM value / 1000) (float type)
• getCreativeId - String. Returns a unique ID of the campaign's creative.
• getAdDomain- String. Returns the Android package name.
• getCreativeUrl - String. Returns the URL of the campaign for User Acquisition campaign type, or the package name for Re-engagement campaign type.
• getCampaignID - String. Returns a unique ID of the campaign
• getCategory - String. Returns the campaign category name.

Optional search keyword

rewardedAd.getECPM(
    context = context,
    onECPMLoaded = callback,
    searchKeyword = "games"
)