---
agentTools:
  projectIndex: https://developers.appnext.com/llms.txt
---

# 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.:

```kotlin
val rewardedAd = RewardedAd("YOUR_PLACEMENT_ID")
```

## Step 2. Load the Rewarded Ad

Call loadAds() before showing the rewarded ad..

```kotlin
rewardedAd.loadAds(context)
```

With optional load callback:

```kotlin
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:

```kotlin
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.

```kotlin
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.

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

**Ad Callback**

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

```kotlin
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.

```kotlin
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.

```kotlin
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.

```kotlin
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

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