Skip to main content

Getting Started

Rewarded ads are an ad format where users can receive rewards after watching a full-screen video ad or a playable ad. This guide explains how to integrate rewarded ads using the NAM SDK.

Before You Begin​

  • Ad Unit ID is required to call ads.
    • Please complete the process of setting up the ad provider, inventory settings, and registering ad units through the NAM Admin.
    • For related details, please contact the NAM administrator.
  • If there are other Views overlaying the ad, exposure measurement may not work properly in some cases, which could negatively impact performance metrics.

[Step 1] Complete NAM SDK Integration​

Please refer to Getting Started.

The following assumes that the NAM SDK integration has been completed.

[Step 2] GfpRewardedAdManager Initialization​

To use rewarded ads, you need to initialize the GfpRewardedAdManager. At this time, you must create an Ad Unit ID required for the ad request and an AdParam object containing runtime information (e.g., targeting information) for a single ad request, and pass them as parameters.

class MainActivity : Activity() {
    private var rewardedAdManager: GfpRewardedAdManager? = null;

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        // Create a new ad parameter.
        val adParam = AdParam.Builder()
            .setAdUnitId("YOUR_AD_UNIT_ID")
            ...
            .build()

        // Create a new GfpRewardedAdManager.
        rewardedAdManager = GfpRewardedAdManager(this, adParam)
    }
}

[Step 3] RewardedAdListener Configuration​

The RewardedAdListener is a listener that receives the load and display status of rewarded ads. It handles events related to the loading and display of GfpRewardedAdManager. Before loading a rewarded ad, you must configure the RewardedAdListener as shown below.

rewardedAdManager.setAdListener(object: RewardedAdListener() {
    override fun onAdLoaded(ad: GfpRewardedAd) {
        // Called when an ad is loaded.
        // You can show the ad here.
    }

    override fun onAdStarted(ad: GfpRewardedAd) {
        // Called when an ad is started or shown.
    }

    override fun onAdClicked(ad: GfpRewardedAd) {
        // Called when an ad is clicked.
    }

    override fun onAdClosed(ad: GfpRewardedAd) {
        // Called when an ad is closed.
    }

    override fun onAdCompleted(ad: GfpRewardedAd) {
        // Called when an ad is completed.
        // You can use this event to initialize your reward
    }

    override fun onError(ad: GfpRewardedAd, error: GfpError) {
        // Called when an error happened while the ad is
        // attempting to load or rendering an ad.
    }
}

[Step 4] Load an ad​

You can load an ad using the loadAd() method of GfpRewardedAdManager. If the ad is successfully loaded, the onAdLoaded() method of RewardedAdListener will be called. If the ad fails to load, the onError() method will be called.

caution

You need to load ads on the UI thread.

caution

To reuse a previously declared GfpRewardedAdManager for ad requests, you must call only loadAd() without calling destroy(). If you call destroy() before calling loadAd(), the request will occur with resources already released, which may result in issues such as not receiving ad events.

class MainActivity : Activity() {
    private var rewardedAdManager: GfpRewardedAdManager? = null;

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        // Create a new ad parameter.
        val adParam = AdParam.Builder()
            .setAdUnitId("YOUR_AD_UNIT_ID")
            ...
            .build()

        // Create a new GfpRewardedAdManager.
        rewardedAdManager = GfpRewardedAdManager(this, adParam).run {
            // Set the ad listener
            setAdListener(object: RewardedAdListener() {
                override fun onAdLoaded(ad: GfpRewardedAd) {
                    // Called when an ad is loaded.
                    // You can show the ad here.
                }

                override fun onError(ad: GfpRewardedAd, error: GfpError) {
                    // Called when an error happened while the ad is
                    // attempting to load or rendering an ad.
                }

                ...
            })

            // Load the rewarded ad
            loadAd()
        }
    }
}

[Step 5] Display an ad​

When an ad is successfully loaded, the onAdLoaded() method of RewardedAdListener is called. At this time, you can display the ad using the GfpRewardedAd object. The integration method may vary depending on whether the rewarded ad is displayed immediately or after a certain period.

info

The GfpRewardedAd parameter, which is commonly passed to all methods of RewardedAdListener, is the same object as the GfpRewardedAdManager used to load the ad.

info

An ad displayed using the showAd() method cannot be displayed again, even if showAd() is called again.

1. Immediate Display​

The following is an example of displaying a rewarded ad immediately after it is loaded.

override fun onAdLoaded(ad: GfpRewardedAd) {
    // Rewarded ad is loaded and ready to be displayed
    ad.show(this)
}

2. Display After a Certain Period​

The following is a simple example of displaying a rewarded ad 10 minutes after it is loaded. Please note that the code below is for reference purposes only.

info

Since rewarded ads have an expiration time, you must use the isAdInvalidated() method to check whether the ad has expired when displaying a preloaded and cached ad. If you display an expired ad, you will not receive rewards for the ad exposure.

class MainActivity : Activity() {
    private var rewardedAdManager: GfpRewardedAdManager? = null;

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        // Create a new GfpRewardedAdManager.
        rewardedAdManager = GfpRewardedAdManager(this, adParam).run {
            // Set the ad listener
            setAdListener(object: RewardedAdListener() {
                override fun onAdLoaded(ad: GfpRewardedAd) {
                    showAdWithDelay()
                }

                ...
            })

            // Load the rewarded ad
            loadAd()
        }
    }

    private fun showAdWithDelay() {
        val handler = Handler(Looper.getMainLooper())
        handler.postDelayed({
            rewardedAdManager?.run {
                // Check if ad is already expired or invalidated,
                // and do not show ad if that is the case.
                // You will not get paid to show an invalidated ad.
                if (!isAdInvalidated()) {
                    return
                }

                showAd(this@MainActivity)
            }
        }, 10 * 60 * 1000) // 10 minutes delay
    }
}

[Step 6] Release Resources​

After displaying a rewarded ad, you must use the destroy() method to release the resources allocated to the ad.

caution

To reuse a previously declared GfpRewardedAdManager for ad requests, you must call only loadAd() without calling destroy(). If you call destroy() before calling loadAd(), the request will occur with resources already released, which may result in issues such as not receiving ad events.

caution

You must call destroy() for all rewarded ads, even if they are not used or referenced.

As shown in the example below, you must release all references to GfpRewardedAdManager used within an Activity in the onDestroy() method of the Activity.

override fun onDestroy() {
    rewardedAdManager?.destroy()
    rewardedAdManager = null
    super.onDestroy()
}