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.
- This ViewGroup must be set as the assetsContainer of GfpNativeAdView during the native ad rendering process.
- 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.
- Kotlin
- Java
// 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()
// Create a new ad parameter.
AdParam adParam = new AdParam.Builder()
.setAdUnitId("YOUR_AD_UNIT_ID")
...
.build();
// Create a new ad loader.
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
.withNativeAd(new GfpNativeAd.OnNativeAdLoadedListener() {
@Override
public void onNativeAdLoaded(GfpNativeAd nativeAd) {
// Show the native ad.
}
})
.withAdListener(new 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.
- Kotlin
- Java
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()
GfpAdLoader adLoader = new GfpAdLoader.Builder(this, adParam)
...
.withAdListener(new AdEventListener() {
@Override
public void onAdClicked() {
// Called when an ad is clicked.
}
@Override
public void onAdImpression() {
// Called when an impression is recorded for an ad.
}
@Override
public void onAdMuted() {
// Called when an ad is muted.
}
@Override
public void onError(GfpError error, GfpResponseInfo responseInfo) {
// 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.
You need to load ads on the UI thread.
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.
- Kotlin
- Java
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()
}
}
public class ExampleActivity extends AppCompatActivity {
private GfpAdLoader adLoader;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_example);
// Create a new ad parameter.
AdParam adParam = new AdParam.Builder()
.setAdUnitId("YOUR_AD_UNIT_ID")
.build();
// Create a new ad loader
adLoader = new GfpAdLoader.Builder(this, adParam)
.withNativeAd(new GfpNativeAd.OnNativeAdLoadedListener() {
@Override
public void onNativeAdLoaded(GfpNativeAd nativeAd) {
// Show the native ad.
}
})
.withAdListener(new 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.
- Kotlin
- Java
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)
}
}
public class ExampleActivity extends AppCompatActivity {
private GfpAdLoader adLoader;
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
...
// Create a new ad loader
adLoader = new GfpAdLoader.Builder(this, adParam)
.withNativeAd(new GfpNativeAd.OnNativeAdLoadedListener() {
@Override
public void onNativeAdLoaded(GfpNativeAd nativeAd) {
// Assumes you have a native ad container FrameLayout in your View layout
FrameLayout nativeAdContainer = findViewById(R.id.native_ad_container);
// This method sets the assets into the ad view
inflateAd(nativeAdContainer, nativeAd);
}
})
.withAdListener(new AdEventListener() {
...
})
.build();
// Load the native ad
adLoader.loadAd();
}
private void inflateAd(ViewGroup parent, GfpNativeAd nativeAd) {
// Assumes that your native ad layout is in a file call native_ad.xml
GfpNativeAdView nativeAdView = (GfpNativeAdView) getLayoutInflater()
.inflate(R.layout.native_ad, parent);
// Locate the GfpAdChoicesView, and call the GfpNativeAdView's setAdChoicesView method to register it.
GfpAdChoicesView adChoicesView = nativeAdView.findViewById(R.id.ad_choices_view);
nativeAdView.setAdChoicesView(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.
FrameLayout assetsContainer = nativeAdView.findViewById(R.id.assets_container);
nativeAdView.setAssetsContainer(assetsContainer);
// Locate the ImageView that will hold the ad icon, set its image, and call the
// GfpNativeAdView's setIconView method to register it.
ImageView iconView = nativeAdView.findViewById(R.id.ad_icon);
Image icon = nativeAd.getIcon();
if (icon != null) {
iconView.setImageDrawable(icon.getDrawable());
iconView.setVisibility(View.VISIBLE);
nativeAdView.setIconView(iconView);
} else {
iconView.setVisibility(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.
GfpMediaView mediaView = nativeAdView.findViewById(R.id.ad_media);
nativeAdView.setMediaView(mediaView);
// Create native UI with text asset
TextView titleView = nativeAdView.findViewById(R.id.ad_title);
TextView bodyView = nativeAdView.findViewById(R.id.ad_body);
TextView advertiserView = nativeAdView.findViewById(R.id.ad_advertiser);
Button callToActionView = nativeAdView.findViewById(R.id.ad_call_to_action);
// Set the Text, and and use the GfpNativeView's setter method to register it.
titleView.text = nativeAd.getTitle();
nativeAdView.setTitleView(titleView);
bodyView.text = nativeAd.getBody();
nativeAdView.setBodyView(bodyView);
advertiserView.text = nativeAd.getAdvertiserName();
nativeAdView.setAdvertiserView(advertiserView);
callToActionView.text = nativeAd.getCallToAction();
nativeAdView.setCallToActionView(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.
- Kotlin
- Java
val nativeAdView = layoutInflater.inflate(R.layout.native_ad_layout, parent) as GfpNativeAdView
GfpNativeAdView nativeAdView = (GfpNativeAdView) getLayoutInflater()
.inflate(R.layout.native_ad, parent);
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.
If the task of registering adChoicesView is omitted, an Exception will occur.
- Kotlin
- Java
val adChoicesView: GfpAdChoicesView = nativeAdView.findViewById(R.id.ad_choices_view)
nativeAdView.adChoicesView = adChoicesView
GfpAdChoicesView adChoicesView = nativeAdView.findViewById(R.id.ad_choices_view);
nativeAdView.setAdChoicesView(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.
If the task of registering assetsContainer is omitted, an Exception will occur.
- Kotlin
- Java
val assetsContainer: FrameLayout = nativeAdView.findViewById(R.id.assets_container)
nativeAdView.assetsContainer = assetsContainer
FrameLayout assetsContainer = nativeAdView.findViewById(R.id.assets_container);
nativeAdView.setAssetsContainer(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.
- Kotlin
- Java
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
}
ImageView iconView = nativeAdView.findViewById(R.id.ad_icon);
Image icon = nativeAd.getIcon();
if (icon != null) {
iconView.setImageDrawable(icon.getDrawable());
iconView.setVisibility(View.VISIBLE);
nativeAdView.setIconView(iconView);
} else {
iconView.setVisibility(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.
- Kotlin
- Java
val mediaView: GfpMediaView = nativeAdView.findViewById(R.id.ad_media)
nativeAdView.mediaView = mediaView
GfpMediaView mediaView = nativeAdView.findViewById(R.id.ad_media);
nativeAdView.setMediaView(mediaView);
6. Register the remaining text-based assets
Set strings to the remaining text-based asset Views and register them with GfpNativeAdView.
- Kotlin
- Java
// 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
// Create native UI with text asset
TextView titleView = nativeAdView.findViewById(R.id.ad_title);
TextView bodyView = nativeAdView.findViewById(R.id.ad_body);
TextView advertiserView = nativeAdView.findViewById(R.id.ad_advertiser);
Button callToActionView = nativeAdView.findViewById(R.id.ad_call_to_action);
// Set the Text, and and use the GfpNativeView's setter method to register it.
titleView.text = nativeAd.getTitle();
nativeAdView.setTitleView(titleView);
bodyView.text = nativeAd.getBody();
nativeAdView.setBodyView(bodyView);
advertiserView.text = nativeAd.getAdvertiserName();
nativeAdView.setAdvertiserView(advertiserView);
callToActionView.text = nativeAd.getCallToAction();
nativeAdView.setCallToActionView(callToActionView);
7. GfpNativeAd Registration
As the final step, register the GfpNativeAd object.
- Kotlin
- Java
nativeAdView.setNativeAd(nativeAd)
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.
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.
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.
- Kotlin
- Java
override fun onDestroy() {
adLoader?.destroy()
super.onDestroy()
}
@Override
public void onDestroy() {
if (adLoader != null) {
adLoader.cancel();
}
super.onDestroy();
}