Skip to main content

Getting Started

Interstitial ads are a type of ad format that occupies the entire screen of the app and is typically displayed naturally during moments when app usage is temporarily paused, such as during screen transitions within the app. This guide explains how to integrate interstitial 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] Initialize GfpInterstitialAdManager​

To use interstitial ads, you need to initialize the GfpInterstitialAdManager. At this time, you must create an Ad Unit ID required for ad requests 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 interstitialAdManager: GfpInterstitialAdManager? = null;

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

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

        // Create a new GfpInterstitialAdManager.
        interstitialAdManager = GfpInterstitialAdManager(this, adParam)
    }
}

[Step 3] Set InterstitialAdListener​

The InterstitialAdListener is a listener that receives the load and display status of interstitial ads. It handles events related to the loading and display of GfpInterstitialAdManager. Before loading interstitial ads, you must set the InterstitialAdListener as shown below.

interstitialAdManager.setAdListener(object: InterstitialAdListener() {
    override fun onAdLoaded(ad: GfpInterstitialAd) {
        // Called when an ad is loaded.
        // You can show the ad here.
    }

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

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

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

    override fun onError(ad: GfpInterstitialAd, 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 by calling the loadAd() method of GfpInterstitialAdManager. If the ad is successfully loaded, the onAdLoaded() method of InterstitialAdListener 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 GfpInterstitialAdManager 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 interstitialAdManager: GfpInterstitialAdManager? = null;

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

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

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

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

                ...
            })

            // Load the ad
            loadAd()
        }
    }
}

[Step 5] Display an ad​

When an ad is successfully loaded, the onAdLoaded method of InterstitialAdListener is called. At this point, you can use the GfpInterstitialAd object to display the ad. The integration method may vary depending on whether the interstitial ad is displayed immediately or after a certain period of time.

info

The GfpInterstitialAd parameter, which is commonly passed to all methods of InterstitialAdListener, is the same object as the GfpInterstitialAdManager used to load the ad.

info

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

1. Immediate Display​

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

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

2. Display after a certain period of time​

Here is a simple example of displaying an interstitial ad 10 minutes after it has been loaded. Please note that the code below is for reference purposes only.

info

Since interstitial ads have an expiration time, you must use the isAdInvalidated() method to check if the ad has expired when displaying a preloaded and cached ad. Displaying an expired ad will not grant rewards for ad exposure.

class MainActivity : Activity() {
    private var interstitialAdManager: GfpInterstitialAdManager? = null;

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

        // Create a new GfpInterstitialAdManager.
        interstitialAdManager = GfpInterstitialAdManager(this, adParam).run {
            // Set the ad listener
            setAdListener(object: InterstitialAdListener() {
                override fun onAdLoaded(ad: GfpInterstitialAd) {
                    showAdWithDelay()
                }

                ...
            })

            // Load the interstitial ad
            loadAd()
        }
    }

    private fun showAdWithDelay() {
        val handler = Handler(Looper.getMainLooper())
        handler.postDelayed({
            interstitialAdManager?.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 an interstitial ad, you must use the destroy() method to release the resources allocated to the ad.

caution

To reuse a previously declared GfpInterstitialAdManager 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 should release all references to GfpInterstitialAdManager used within an Activity in the onDestroy() method of the Activity.

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