Skip to main content

Getting Started

Banner ads are rectangular ad formats that occupy part of the app layout and are often placed at the top or bottom of the screen or inline within scrollable content.


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] Define the Ad View Container

First, add a ViewGroup to the layout XML file to serve as the container for the banner ad.

In the example below, a ViewGroup with the id banner_ad_container is declared to display the banner ad.

<!-- Banner ad view container -->
<FrameLayout
android:id="@+id/banner_ad_container"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_centerInParent="true"
android:layout_alignParentBottom="true"/>

[Step 3] Add GfpBannerAdView to the Layout

Create a GfpBannerAdView and add it to your app's layout. When creating a GfpBannerAdView, you must pass an Ad Unit ID, which is essential for ad requests, along with an AdParam object containing runtime information (e.g., targeting information) for a single ad request.

For more details on AdParam, please refer to Ad Parameters.

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

// Create a new banner ad view.
val bannerAdView = GfpBannerAdView(this, adParam)

// Replace ad container with new banner ad view.
bannerAdContainer.removeAllViews();
bannerAdContainer.addView(bannerAdView)

[Step 4] Additional Customization (Optional)

While not mandatory, banner ads offer Banner Ad Options options such as setting the banner ad layout type and configuring a timeout for individual ad requests to provide a better ad experience. For more details, please refer to the Banner Ad Options guide.

[Step 5] Setting Up Ad Event Listeners

Events related to the lifecycle of banner ads (e.g., load, click, impression, error, ...) can be received through the BannerAdListener.

info

When receiving ad events, you can obtain various information about the ad that triggered the event through the GfpBannerAd parameter. For example, GfpBannerAd.getAdProviderName() allows you to identify the name of the ad provider for the currently loaded ad.

info

To ensure proper event delivery, it is recommended to set up the BannerAdListener before loading the banner ad.

bannerAdView.setAdListener(object : BannerAdListener() {
override fun onAdLoaded(ad: GfpBannerAd) {
// Called when an banner ad is loaded.
}

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

override fun onAdImpression(ad: GfpBannerAd) {
// Called when an impression is recorded for an banner ad.
}

override fun onAdMuted(ad: GfpBannerAd) {
// (Only for NDA module) Called when an banner ad is muted.
}

override fun onAdMetaChanged(ad: GfpBannerAd, params: Map<String, String>) {
// Called when the meta data of the banner ad changes.
}

override fun onAdSizeChanged(ad: GfpBannerAd) {
// Called when the banner ad is changed in size.
}

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

[Step 6] Load an ad

Once the configuration for GfpBannerAdView is complete, you can load ads using the loadAd() method of GfpBannerAdView.

caution

You need to load ads on the UI thread.

caution

To reuse a pre-declared GfpBannerAdView for ad requests, you should call only loadAd() without calling the destroy() method. If you call loadAd() after calling the destroy() method, the request will occur with resources already released, which may result in issues such as not receiving ad events.

class ExampleActivity : AppCompatActivity() {
private var bannerAdView: GfpBannerAdView? = null

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_example)

// The view container of banner ad view
val bannerAdContainer = findViewById(R.id.banner_ad_container)

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

// Create a new banner ad view
bannerAdView = GfpBannerAdView(this, adParam)

// Sets the listener for banner ad events
bannerAdView.setAdListener(object : BannerAdListener() {
override fun onAdLoaded(ad: GfpBannerAd?) {
// Called when an banner ad is loaded.
}

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

override fun onAdImpression(ad: GfpBannerAd?) {
// Called when an impression is recorded for an banner ad.
}

override fun onAdMuted(ad: GfpBannerAd?) {
// (Only for NDA module) Called when an banner ad is muted.
}

override fun onAdMetaChanged(ad: GfpBannerAd?, params: MutableMap<String, String>?) {
// Called when the meta data of the banner ad changes.
}

override fun onAdSizeChanged(ad: GfpBannerAd?) {
// Called when the banner ad is changed in size.
}

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

// Add the banner ad view to the view container
bannerAdContainer.addView(bannerAdView)

// Load the banner ad
bannerAdView.loadAd()
}

override fun onDestroy() {
bannerAdView?.destroy()
super.onDestroy()
}
}


[Step 7] Release resources

You should use the destroy() method to release the resources allocated to the ad once the banner ad display is finished.

caution

To reuse a pre-declared GfpBannerAdView for ad requests, you should call only loadAd() without calling the destroy() method. If you call loadAd() after calling the destroy() method, the request will occur with resources already released, which may result in issues such as not receiving ad events.

caution

destroy() must be called for all banner ads, even if they are not used or referenced.

In the onDestroy()) method of the Activity, you should ensure that all references to GfpBannerAdView used within the Activity are released, as shown in the example below:

override fun onDestroy() {
bannerAdView?.destroy()
super.onDestroy()
}