Skip to main content

Getting Started

Native ads allow you to monetize your app in a way that aligns with the visual design of your app by using UI components provided by the platform.

When a native ad is loaded, the app receives an ad object containing ad assets, and the app integrated with the SDK renders the ad content using those assets.


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, you need to add a ViewGroup that will serve as the container for the native ad in the layout XML file.

In the example below, a ViewGroup with the id native_ad_container is declared as the container for the native ad.

<!-- native ad view container -->
<FrameLayout
android:id="@+id/native_ad_container"
android:layout_width="match_parent"
android:layout_height="wrap_content"/>

[Step 3] Define GfpNativeAdView

After defining the ViewGroup layout where the native ad will be displayed, you need to configure the layout where the native ad will be rendered.

GfpNativeAdView is a ViewGroup mapped to GfpNativeAd. The individual views used to render the ad assets provided by GfpNativeAd must be child views of GfpNativeAdView.

The following is an example of a layout configuration that displays ad assets using a FrameLayout with the id assets_container.

<?xml version="1.0" encoding="utf-8"?>
<com.naver.gfpsdk.GfpNativeAdView xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/gfp_native_ad"
android:layout_width="match_parent"
android:layout_height="wrap_content">

<FrameLayout
android:id="@+id/assets_container"
android:layout_width="match_parent"
android:layout_height="wrap_content">

<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_gravity="center"
android:background="#FFFFFF"
android:minHeight="50dp"
android:orientation="vertical">

<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="vertical"
android:padding="10dp">

<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="12dp"
android:orientation="horizontal">

<ImageView
android:id="@+id/ad_icon"
android:layout_width="46dp"
android:layout_height="46dp"
android:layout_marginRight="10dp"
android:adjustViewBounds="true" />

<LinearLayout
android:layout_width="0dp"
android:layout_height="wrap_content"
android:layout_gravity="center_vertical"
android:layout_weight="1"
android:orientation="vertical">

<TextView
android:id="@+id/ad_title"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="4dp"
android:ellipsize="end"
android:lines="1"
android:textColor="#000000"
android:textSize="12dp" />

<TextView
android:id="@+id/ad_sponsored"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:textColor="#999999"
android:textSize="12dp" />

</LinearLayout>

<com.naver.gfpsdk.GfpAdChoicesView
android:id="@+id/ad_choices_view"
android:layout_width="20dp"
android:layout_height="20dp"
android:layout_gravity="center_vertical"
android:layout_marginLeft="10dp" />

</LinearLayout>

<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="vertical">

<TextView
android:id="@+id/ad_body"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="12dp"
android:ellipsize="end"
android:maxLines="2"
android:textColor="#000000"
android:textSize="15dp" />

<com.naver.gfpsdk.GfpMediaView
android:id="@+id/ad_media"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="12dp" />

<LinearLayout
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="horizontal">

<LinearLayout
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_weight="3"
android:orientation="vertical">

<TextView
android:id="@+id/ad_advertiser"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:ellipsize="end"
android:lines="1"
android:textColor="@android:color/darker_gray"
android:textSize="13dp" />

<TextView
android:id="@+id/ad_social_context"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:ellipsize="end"
android:gravity="center_vertical"
android:lines="1"
android:textColor="@android:color/black"
android:textSize="13dp" />

</LinearLayout>

<Button
android:id="@+id/ad_call_to_action"
android:layout_width="100dp"
android:layout_height="40dp"
android:background="#3c3c3c"
android:paddingLeft="3dp"
android:paddingRight="3dp"
android:textColor="#ffffff"
android:textSize="13dp" />

</LinearLayout>
</LinearLayout>
</LinearLayout>
</LinearLayout>
</FrameLayout>
</com.naver.gfpsdk.GfpNativeAdView>

Points to Note

When configuring a layout that includes GfpNativeAdView, the following constraints must be strictly followed:

  • The top-level view must be GfpNativeAdView.
  • The child views of GfpNativeAdView must be specified as ViewGroup to hold assets.
  • AdChoices must be included using GfpAdChoiceView.
    • Ads provided by the DFP module automatically render AdChoices as a separate view through the DFP SDK.
    • For ads provided by other modules, AdChoices will be rendered in this area.
    • The width and height of GfpAdChoiceView must be at least 20dp, with the recommended size being 20dp for both width and height.
  • The area where the main image or video (not the icon) is rendered must be declared as GfpMediaView.

[Step 4] Build GfpAdLoader

Native ads are loaded through the GfpAdLoader class, which can be created using the GfpAdLoader.Builder class that allows various customizations during the creation process. By configuring the withNativeAd() method, which is considered a declaration to load native ads, you can load native ads when building the GfpAdLoader.

When building the GfpAdLoader, you must create and pass an AdParam object as a parameter, which includes essential information for ad requests, such as the Ad Unit ID, as well as 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 ad loader.
val adLoader = GfpAdLoader.Builder(this, adParam)
.withNativeAd { nativeAd ->
// Show the native ad.
}
.withAdListener(object: AdEventListener() {
...
})
.build()

As shown in the example above, you can create a GfpAdLoader capable of receiving native ads using the withNativeAd() method. When a native ad is successfully loaded, the onNativeAdLoaded() method of the GfpNativeAd.OnNativeAdLoadedListener() declared as a parameter is called.


[Step 5] Ad Events

Through the withAdListener() method provided by GfpAdLoader.Builder, you can receive various events related to the ad lifecycle.

If there are events you want to receive, you can selectively override and implement the methods provided by AdEventListener.

val adLoader = GfpAdLoader.Builder(this, adParam)
...
.withAdListener(object : AdEventListener() {
override fun onAdClicked() {
// Called when an ad is clicked.
}

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

override fun onAdMuted() {
// Called when an ad is muted.
}

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

[Step 6] Load an ad

Once the GfpAdLoader build is complete, you can load ads using the loadAd() method of GfpAdLoader.

caution

You need to load ads on the UI thread.

caution

To request ads using a pre-declared GfpAdLoader without reinitializing, you must call only loadAd() without calling cancel(). If you call the cancel() method and then call loadAd(), issues such as not receiving ad events may occur because the request is made with resources already released.

class ExampleActivity : AppCompatActivity() {
private lateinit var adLoader: GfpAdLoader

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

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

// Create a new ad loader
adLoader = GfpAdLoader.Builder(this, adParam)
.withNativeAd { nativeAd ->
// Show the native ad.
}
.withAdListener(object: AdEventListener() {
...
})
.build()

// Load the native ad
adLoader.loadAd()
}
}

[Step 7] Display an ad

When a native ad is successfully loaded, a GfpNativeAd object is received. All native ad assets provided by GfpNativeAd must be rendered by mapping them to Views that match the characteristics of the assets under GfpNativeAdView.

Below is an example of creating a GfpNativeAdView and applying a GfpNativeAd to it.

class ExampleActivity : AppCompatActivity() {
private lateinit var adLoader: GfpAdLoader

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

// Create a new ad loader
adLoader = GfpAdLoader.Builder(this, adParam)
.withNativeAd { nativeAd ->
// Assumes you have a native ad container FrameLayout in your View layout
val nativeAdContainer: FrameLayout = findViewById(R.id.native_ad_container)

// This method sets the assets into the ad view
inflateAd(nativeAdContainer, nativeAd)
}
.withAdListener(object: AdEventListener() {
...
})
.build()


// Load the native ad
adLoader.loadAd()
}

private fun inflateAd(parent: ViewGroup, nativeAd: GfpNativeAd) {
// Assumes that your native ad layout is in a file call native_ad.xml
val nativeAdView = layoutInflater.inflate(R.layout.native_ad_layout, parent) as GfpNativeAdView

// Add the GfpAdChoicesView
val adChoicesView: GfpAdChoicesView = nativeAdView.findViewById(R.id.ad_choices_view)
nativeAdView.adChoicesView = adChoicesView

// You need to register the ViewGroup that contains all the views mapped to the native ad assets as assetsContainer.
// This ViewGroup should be provided as a separate ViewGroup and must be a subview of GfpNativeAdView.
val assetsContainer: FrameLayout = nativeAdView.findViewById(R.id.assets_container)
nativeAdView.assetsContainer = assetsContainer

// Locate the ImageView that will hold the ad icon, set its image, and call the
// GfpNativeAdView's setIconView method to register it.
val iconView: ImageView = nativeAdView.findViewById(R.id.ad_icon)
val icon = nativeAd.icon
if (icon != null) {
iconView.setImageDrawable(icon.drawable)
iconView.visibility = View.VISIBLE
nativeAdView.iconView = iconView
} else {
iconView.visibility = View.GONE
}

// You're required to use the GfpMediaView instead of the ImageView or VideoView
// if you want to include a main image or video asset in the layout for your native ad.
val mediaView: GfpMediaView = nativeAdView.findViewById(R.id.ad_media)
nativeAdView.mediaView = mediaView

// Create native UI with text asset
val titleView: TextView = nativeAdView.findViewById(R.id.ad_title)
val bodyView: TextView = nativeAdView.findViewById(R.id.ad_body)
val advertiserView: TextView = nativeAdView.findViewById(R.id.ad_advertiser)
val callToActionView: Button = nativeAdView.findViewById(R.id.ad_call_to_action)

// Set the Text, and and use the GfpNativeView's properties to register it.
titleView.text = nativeAd.title
nativeAdView.titleView = titleView

bodyView.text = nativeAd.body
nativeAdView.bodyView = bodyView

advertiserView.text = nativeAd.advertiserName
nativeAdView.advertiserView = advertiserView

callToActionView.text = nativeAd.callToAction
nativeAdView.callToActionView = callToActionView

// Call the GfpNativeAdView's setNativeAd method to register the native ad object.
nativeAdView.setNativeAd(nativeAd)

// Ensure that the adContainer view doesn't already contain an ad view.
nativeAdContainer.removeAllViews()

// Place the native ad view into the adContainer
nativeAdContainer.addView(nativeAdView)
}
}

Here are the individual tasks:

1. Inflate GfpNativeAdView

The following code inflates an XML layout containing a view for displaying native ads and then finds a reference to the GfpNativeAdView. If the GfpNativeAdView is already present in an Activity or Fragment, or if the instance is dynamically created without using a layout file, you can reuse the existing object.

val nativeAdView = layoutInflater.inflate(R.layout.native_ad_layout, parent) as GfpNativeAdView

2. Register GfpAdChoicesView containing AdChoices

AdChoices is an industry-standard icon that provides a link for managing ad personalization or allows users to report illegal or policy-violating content. Therefore, the GfpAdChoicesView, which can include AdChoices, must be included when configuring the layout and must be registered using the adChoicesView of GfpNativeAdView.

caution

If the task of registering adChoicesView is omitted, an Exception will occur.

val adChoicesView: GfpAdChoicesView = nativeAdView.findViewById(R.id.ad_choices_view)
nativeAdView.adChoicesView = adChoicesView

3. Register the ViewGroup containing ad assets

The ViewGroup containing all Views mapped to native ad assets must be registered as the assetsContainer of GfpNativeAdView. This ViewGroup should be provided as a separate ViewGroup and must be a child View of GfpNativeAdView.

caution

If the task of registering assetsContainer is omitted, an Exception will occur.

val assetsContainer: FrameLayout = nativeAdView.findViewById(R.id.assets_container)
nativeAdView.assetsContainer = assetsContainer

4. Register Icon Asset

The Icon asset represents the advertiser's icon. Since the Icon asset may not be included depending on the ad provider or ad material, it should be handled with this in mind.

val iconView: ImageView = nativeAdView.findViewById(R.id.ad_icon)
val icon = nativeAd.icon
if (icon != null) {
iconView.setImageDrawable(icon.drawable)
iconView.visibility = View.VISIBLE
nativeAdView.iconView = iconView
} else {
iconView.visibility = View.GONE
}

5. Register GfpMediaView

To include image or video assets in the native ad layout, you must use GfpMediaView.

GfpMediaView is a specialized View designed to display images or videos. Unlike other Views mapped to native ad assets, it only needs to be registered with GfpNativeAdView without additional mapping of ad assets.

val mediaView: GfpMediaView = nativeAdView.findViewById(R.id.ad_media)
nativeAdView.mediaView = mediaView

6. Register the remaining text-based assets

Set strings to the remaining text-based asset Views and register them with GfpNativeAdView.

// Create native UI with text asset
val titleView: TextView = nativeAdView.findViewById(R.id.ad_title)
val bodyView: TextView = nativeAdView.findViewById(R.id.ad_body)
val advertiserView: TextView = nativeAdView.findViewById(R.id.ad_advertiser)
val callToActionView: Button = nativeAdView.findViewById(R.id.ad_call_to_action)

// Set the Text, and and use the GfpNativeView's properties to register it.
titleView.text = nativeAd.title
nativeAdView.titleView = titleView

bodyView.text = nativeAd.body
nativeAdView.bodyView = bodyView

advertiserView.text = nativeAd.advertiserName
nativeAdView.advertiserView = advertiserView

callToActionView.text = nativeAd.callToAction
nativeAdView.callToActionView = callToActionView

7. GfpNativeAd Registration

As the final step, register the GfpNativeAd object.

nativeAdView.setNativeAd(nativeAd)

[Step 8] Release Resources

When the display of a native ad is complete, the cancel() method must be called to release the resources allocated to the ad.

caution

To request an ad by reusing a pre-declared GfpAdLoader, you must call only loadAd() without calling cancel(). If loadAd() is called after invoking cancel(), issues such as failing to receive ad events may occur because the request is made with resources already released.

info

The cancel() method must be called for all ads, even if they are unused or unreferenced.

The following example demonstrates releasing all references to GfpAdLoader used within an Activity in the onDestroy() method.

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