Skip to main content
danger
Android SDK 3.0.2 is outdated. The most recent stable version is here.
Version: 3.0.2

Native

Native ad is a flexible type of advertising. You can adapt the display to your UI by preparing a template.

You can use our demo app as a reference project.

Demo App

Cache

To cache native ads, use:

Appodeal.cache(this, Appodeal.NATIVE)

To cache multiple native ads, use:

Appodeal.cache(this, Appodeal.NATIVE, 3)
info

The number of cached ads is not guaranteed and could be less than requested.

Check If Ad Is Loaded

Appodeal.isLoaded(Appodeal.NATIVE)

Get Loaded Native Ads

To get loaded native ads, use the following method:

val nativeAds: List<NativeAd> = Appodeal.getNativeAds(amount)
note

Once you get the ads, they are removed from our SDK cache.

Callbacks

Appodeal.setNativeCallbacks(object : NativeCallbacks {
override fun onNativeLoaded() {
// Called when native ads are loaded
}
override fun onNativeFailedToLoad() {
// Called when native ads are failed to load
}
override fun onNativeShown(NativeAd nativeAd) {
// Called when native ad is shown
}
override fun onNativeShowFailed(NativeAd nativeAd) {
// Called when native ad show failed
}
override fun onNativeClicked(NativeAd nativeAd) {
// Called when native ads is clicked
}
override fun onNativeExpired() {
// Called when native ads is expired
}
})
info

All callbacks are called on the main thread.

Cache Manually

To disable automatic caching for native ads, use the code below before the SDK initialization:

Appodeal.setAutoCache(Appodeal.NATIVE, false)

Read more on manual caching in our FAQ.

Get Available Native Ads Count

Appodeal.getAvailableNativeAdsCount()

NativeAd Object

After getting loaded native ads using Appodeal.getNativeAds(), a list of NativeAd objects is returned.

Name of methodsTypeMandatoryDescription
nativeAd.titleStringMandatoryTitle of the native ad. Maximum 25 symbols of the title should always be displayed. You can add ellipsis at the end if the title is longer.
nativeAd.callToActionStringMandatoryCall-to-action text. Should be displayed without truncation on a visible button.
nativeAd.descriptionStringOptionalText description of the native ad. If you choose to display the description, you should display maximum 100 characters. You can add ellipsis at the end.
nativeAd.ratingFloatOptionalRating of the app in [0-5] range
nativeAd.ageRestrictionsStringOptionalApp age restriction. May return null.
nativeAd.adProviderStringOptionalGets provider name of native ad.
nativeAd.getProviderView(context: Context)ViewMandatoryIf it doesn’t return null, it’s mandatory to display the provider icon in any corner of the native ad. Used by some networks to display AdChoices or the privacy icon.
nativeAd.containsVideo()BooleanOptionalReturns true, if NativeAd object contains the video.
nativeAd.canShow(placementName: String)BooleanOptionalCheck if native ad can be shown with the placement.
nativeAd.isPrecacheBooleanOptionalCheck if a native ad is precache.
nativeAd.predictedEcpmDoubleOptionalReturns the predicted ecpm for creative.
nativeAd.destroy()UnitMandatoryDestroys the native ad, unregisters from tracking.

Configuration

Native Ads Assets Caching

Set required native media assets for what necessary for the show. Default value is ALL.

//assets caching for NativeIconView and NativeMediaView
Appodeal.setRequiredNativeMediaAssetType(Native.MediaAssetType.ALL)
//assets caching only for NativeIconView
Appodeal.setRequiredNativeMediaAssetType(Native.MediaAssetType.ICON)
//assets caching only for NativeMediaView
Appodeal.setRequiredNativeMediaAssetType(Native.MediaAssetType.IMAGE)

Native Video

To show video native ads, add NativeMediaView to native ad layout.

val adView: NativeAdView = findViewById(R.id.native_layout)
val nativeMediaView: NativeMediaView = adView.findViewById(R.id.appodeal_media_view_content)
if (nativeAd.containsVideo()) {
adView.nativeMediaView = nativeMediaView;
} else {
nativeMediaView.visibility = View.GONE;
}

Native Video Settings

To control whether you want to show video native ads, use the following methods:

// both static image and video native ads will be loaded
Appodeal.setNativeAdType(Native.NativeAdType.Auto)
// only static image native ads will be loaded
Appodeal.setNativeAdType(Native.NativeAdType.NoVideo)
// only video native ads will be loaded.
Appodeal.setNativeAdType(Native.NativeAdType.Video)

Templates

Appodeal SDK provides 3 types of templates for native ads:

  • NativeAdViewNewsFeed;
  • NativeAdViewAppWall;
  • NativeAdViewContentStream.

If you want to use one of these templates, you can add the selected template in the layout:

XML
<com.appodeal.ads.native_ad.views.NativeAdViewNewsFeed
android:id="@+id/native_ad_view_news_feed"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="10dp">
</com.appodeal.ads.native_ad.views.NativeAdViewNewsFeed>

<com.appodeal.ads.native_ad.views.NativeAdViewAppWall
android:id="@+id/native_ad_view_app_wall"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_marginBottom="10dp">
</com.appodeal.ads.native_ad.views.NativeAdViewAppWall>

<com.appodeal.ads.native_ad.views.NativeAdViewContentStream
android:id="@+id/native_ad_view_content_stream"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginBottom="10dp">
</com.appodeal.ads.native_ad.views.NativeAdViewContentStream>

And when you need to show the ad:

val nav_nf: NativeAdViewNewsFeed = mActivity.findViewById(R.id.native_ad_view_news_feed)
nav_nf.setNativeAd(mNativeAd)

val nav_aw: NativeAdViewAppWall = mActivity.findViewById(R.id.native_ad_view_app_wall)
nav_aw.setNativeAd(mNativeAd)

val nav_cs: NativeAdViewContentStream = mActivity.findViewById(R.id.native_ad_view_content_stream)
nav_cs.setNativeAd(mNativeAd)

You can also create a view programmatically and add it to the screen:

val holder: RelativeLayout = mActivity.findViewById(R.id.native_template_holder)
val nativeAdView = NativeAdViewAppWall(mActivity, mNativeAd)
holder.addView(nativeAdView)

TemplateElements

val title: TextView = getTitleView()
val description: TextView = getDescriptionView()
val rating: View = getRatingView()
val ratingBar: RatingBar = getRatingBar()
val providerView: View = getProviderView()
val callToAction: TextView = getCallToActionView()
val iconView: NativeIconView = getNativeIconView()
val mediaView: NativeMediaView = getNativeMediaView()

By default, native ads are labeled «Ad». You can replace it with «Sponsored» for the native templates:

nav.showSponsored(true);

To change the color of the call-to-action button in the native templates, use:

nav.setCallToActionColor(color: Integer)
nav.setCallToActionColor(color: String)

СustomLayout

val nativeAdView: NativeAdView = findViewById(R.id.native_layout)
val tvTitle: TextView = nativeAdView.findViewById(R.id.tv_title)
tvTitle.text = nativeAd.title
nativeAdView.titleView = tvTitle
val tvDescription: TextView = nativeAdView.findViewById(R.id.tv_description)
tvDescription.text = nativeAd.description
nativeAdView.descriptionView = tvDescription
val ratingBar: RatingBar = nativeAdView.findViewById(R.id.rb_rating)
if (nativeAd.rating == 0.0f) {
ratingBar.visibility = View.INVISIBLE
} else {
ratingBar.visibility = View.VISIBLE
ratingBar.rating = nativeAd.rating
ratingBar.stepSize = 0.1f
}
nativeAdView.ratingView = ratingBar
val ctaButton: Button = nativeAdView.findViewById(R.id.b_cta)
ctaButton.text = nativeAd.callToAction
nativeAdView.callToActionView = ctaButton
val providerView: View? = nativeAd.getProviderView(context)
if (providerView != null) {
if (providerView.parent != null && providerView.parent is ViewGroup) {
(providerView.parent as ViewGroup).removeView(providerView)
}
val providerViewContainer: FrameLayout =
nativeAdView.findViewById(R.id.provider_view)
val layoutParams: ViewGroup.LayoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.WRAP_CONTENT,
ViewGroup.LayoutParams.WRAP_CONTENT
)
providerViewContainer.addView(providerView, layoutParams)
}
nativeAdView.providerView = providerView
val tvAgeRestrictions: TextView = nativeAdView.findViewById(R.id.tv_age_restriction)
if (nativeAd.ageRestrictions != null) {
tvAgeRestrictions.text = nativeAd.ageRestrictions
tvAgeRestrictions.visibility = View.VISIBLE
} else {
tvAgeRestrictions.visibility = View.GONE
}
val nativeIconView: NativeIconView = nativeAdView.findViewById(R.id.icon)
nativeAdView.setNativeIconView(nativeIconView)
val nativeMediaView: NativeMediaView = nativeAdView.findViewById(R.id.appodeal_media_view_content)
nativeAdView.nativeMediaView = nativeMediaView
nativeAdView.registerView(nativeAd)

To showNativeAdin custom layout you should use NativeAdView, populate and register the asset views.

Bind assets view to NativeAdView:

nativeAdView.titleView = view: View
nativeAdView.callToActionView = view: View
nativeAdView.ratingView = view: View
nativeAdView.descriptionView = view: View
nativeAdView.providerView = view: View
nativeAdView.setNativeIconView(nativeIconView: NativeIconView)
nativeAdView.nativeMediaView = nativeMediaView: NativeMediaView

And registerNativeAdobject in NativeAdView:

nativeAdView.registerView(nativeAd: NativeAd)
// or nativeAdView.registerView(nativeAd: NativeAd, placementName: String) if you use placements
info

If another NativeAd was registered to this instance of view, it will be automatically unregistered.

To unregister NativeAd from NativeAdView, call:

nativeAdView.unregisterViewForInteraction();

If NativeAdView is reused to display the same ad or to display other ads, it's better to call the unregisterViewForInteraction() method before you can register the same view with another instance of NativeAd.

To destroy NativeAd that was registered to NativeAdView, you should call:

nativeAdView.destroy()

You can't use this instance on NativeAdView after call destroy(). You should hide this view or register another NativeAd.

Integration Example

fun loadNativeAds() {
Appodeal.setRequiredNativeMediaAssetType(Native.MediaAssetType.ICON)
Appodeal.initialize(this, YOUR_APP_KEY, Appodeal.NATIVE, consentValue)
Appodeal.setNativeCallbacks(new NativeCallbacks() {
override fun onNativeLoaded() {
Toast.makeText(MainActivity.this, "onNativeLoaded", Toast.LENGTH_SHORT).show()
}

override fun onNativeFailedToLoad() {
Toast.makeText(MainActivity.this, "onNativeFailedToLoad", Toast.LENGTH_SHORT).show()
}

override fun onNativeShown(NativeAd nativeAd) {
Toast.makeText(MainActivity.this, "onNativeShown", Toast.LENGTH_SHORT).show()
}

override fun onNativeClicked(NativeAd nativeAd) {
Toast.makeText(MainActivity.this, "onNativeClicked", Toast.LENGTH_SHORT).show()
}

override fun onNativeExpired() {
Toast.makeText(MainActivity.this, "onNativeExpired", Toast.LENGTH_SHORT).show()
}
})
}

To show loaded native ad:

fun showNativeAd() {
val loadedNativeAds = Appodeal.getNativeAds(1)
if (loadedNativeAds.isEmpty()) {
//Native Ads not loaded yet
return
}
val nativeAd = loadedNativeAds[0]
val nativeAdView: NativeAdView = findViewById(R.id.native_layout)
val tvTitle: TextView = nativeAdView.findViewById(R.id.tv_title)
tvTitle.text = nativeAd.title
nativeAdView.titleView = tvTitle
val tvDescription: TextView = nativeAdView.findViewById(R.id.tv_description)
tvDescription.text = nativeAd.description
nativeAdView.descriptionView = tvDescription
val ratingBar: RatingBar = nativeAdView.findViewById(R.id.rb_rating)
if (nativeAd.rating == 0f) {
ratingBar.visibility = View.INVISIBLE
} else {
ratingBar.visibility = View.VISIBLE
ratingBar.rating = nativeAd.rating
ratingBar.stepSize = 0.1f
}
nativeAdView.ratingView = ratingBar
val ctaButton: Button = nativeAdView.findViewById(R.id.b_cta)
ctaButton.text = nativeAd.callToAction
nativeAdView.callToActionView = ctaButton
val providerView = nativeAd.getProviderView(context)
if (providerView != null) {
if (providerView.parent != null && providerView.parent is ViewGroup) {
(providerView.parent as ViewGroup).removeView(providerView)
}
val providerViewContainer: FrameLayout = nativeAdView.findViewById(R.id.provider_view)
val layoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.WRAP_CONTENT,
ViewGroup.LayoutParams.WRAP_CONTENT
)
providerViewContainer.addView(providerView, layoutParams)
}
nativeAdView.providerView = providerView
val tvAgeRestrictions: TextView = nativeAdView.findViewById(R.id.tv_age_restriction)
if (nativeAd.ageRestrictions != null) {
tvAgeRestrictions.text = nativeAd.ageRestrictions
tvAgeRestrictions.visibility = View.VISIBLE
} else {
tvAgeRestrictions.visibility = View.GONE
}
val nativeIconView: NativeIconView = nativeAdView.findViewById(R.id.icon)
nativeAdView.setNativeIconView(nativeIconView)
val nativeMediaView: NativeMediaView =
nativeAdView.findViewById(R.id.appodeal_media_view_content)
nativeAdView.nativeMediaView = nativeMediaView
nativeAdView.registerView(nativeAd)
nativeAdView.visibility = View.VISIBLE
}

Native Ad Integration To The Feed

You can use this example to integrate Native Ad to the existing feed in your application:

import android.util.SparseArray
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.widget.Button
import android.widget.FrameLayout
import android.widget.RatingBar
import android.widget.TextView
import androidx.recyclerview.widget.RecyclerView
import com.appodeal.ads.*

/**
* Wrapper adapter to show Native Ad in recycler view with fixed step
*
* @param userAdapter user adapter
* @param nativeStep step show [com.appodeal.ads.NativeAd]
*/
class AppodealWrapperAdapter(
userAdapter: RecyclerView.Adapter<RecyclerView.ViewHolder>,
nativeStep: Int
) : RecyclerView.Adapter<RecyclerView.ViewHolder>(), NativeCallbacks {

private val _userAdapter: RecyclerView.Adapter<RecyclerView.ViewHolder>?
private val userAdapter: RecyclerView.Adapter<RecyclerView.ViewHolder>
get() = requireNotNull(_userAdapter)
private var nativeStep = DEFAULT_NATIVE_STEP
private val nativeAdList = SparseArray<NativeAd?>()

init {
this._userAdapter = userAdapter
this.nativeStep = nativeStep + 1
userAdapter.registerAdapterDataObserver(object : RecyclerView.AdapterDataObserver() {
override fun onChanged() {
super.onChanged()
notifyDataSetChanged()
fillListWithAd()
}

override fun onItemRangeInserted(positionStart: Int, itemCount: Int) {
super.onItemRangeInserted(positionStart, itemCount)
notifyDataSetChanged()
fillListWithAd()
}
})
Appodeal.setNativeCallbacks(this)
fillListWithAd()
}

override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): RecyclerView.ViewHolder {
return if (viewType == VIEW_HOLDER_NATIVE_AD_TYPE) {
val view = LayoutInflater.from(parent.context)
.inflate(R.layout.include_native_ads, parent, false)
NativeCustomAdViewHolder(view)
} else {
userAdapter.onCreateViewHolder(parent, viewType)
}
}

override fun onBindViewHolder(holder: RecyclerView.ViewHolder, position: Int) {
if (holder is NativeCustomAdViewHolder) {
holder.fillNative(nativeAdList[position])
} else {
userAdapter.onBindViewHolder(holder, getPositionInUserAdapter(position))
}
}

override fun getItemCount(): Int {
var resultCount = 0
resultCount += nativeAdsCount
resultCount += userAdapterItemCount
return resultCount
}

override fun getItemViewType(position: Int): Int {
return if (isNativeAdPosition(position)) {
VIEW_HOLDER_NATIVE_AD_TYPE
} else {
userAdapter.getItemViewType(getPositionInUserAdapter(position))
}
}

override fun onViewRecycled(holder: RecyclerView.ViewHolder) {
super.onViewRecycled(holder)
if (holder is NativeCustomAdViewHolder) {
holder.unregisterViewForInteraction()
}
}

/**
* Destroy all used native ads
*/
fun destroyNativeAds() {
for (i in 0 until nativeAdList.size()) {
val nativeAd = nativeAdList.valueAt(i)
nativeAd!!.destroy()
}
nativeAdList.clear()
}

override fun onNativeLoaded() {
fillListWithAd()
}

override fun onNativeFailedToLoad() {}
override fun onNativeShown(nativeAd: NativeAd?) {}
override fun onNativeShowFailed(nativeAd: NativeAd?) {}
override fun onNativeClicked(nativeAd: NativeAd?) {}
override fun onNativeExpired() {}

/**
* @return count of loaded ads [com.appodeal.ads.NativeAd]
*/
private val nativeAdsCount: Int
get() = nativeAdList.size()

/**
* @return user items count
*/
private val userAdapterItemCount: Int
get() = userAdapter.itemCount

/**
* @param position index in wrapper adapter
* @return `true` if item by position is [com.appodeal.ads.NativeAd]
*/
private fun isNativeAdPosition(position: Int): Boolean {
return nativeAdList[position] != null
}

/**
* Method for searching position in user adapter
*
* @param position index in wrapper adapter
* @return index in user adapter
*/
private fun getPositionInUserAdapter(position: Int): Int {
return position - nativeAdList.size().coerceAtMost(position / nativeStep)
}

/**
* Method for filling list with [com.appodeal.ads.NativeAd]
*/
private fun fillListWithAd() {
var insertPosition = findNextAdPosition()
var nativeAd: NativeAd? = null
while (canUseThisPosition(insertPosition) && nativeAdItem.also { nativeAd = it } != null) {
nativeAdList.put(insertPosition, nativeAd)
notifyItemInserted(insertPosition)
insertPosition = findNextAdPosition()
}
}

/**
* Get native ad item
*
* @return [com.appodeal.ads.NativeAd]
*/
private val nativeAdItem: NativeAd?
get() {
val ads = Appodeal.getNativeAds(1)
return if (ads.isNotEmpty()) ads[0] else null
}

/**
* Method for finding next position suitable for [com.appodeal.ads.NativeAd]
*
* @return position for next native ad view
*/
private fun findNextAdPosition(): Int {
return if (nativeAdList.size() > 0) {
nativeAdList.keyAt(nativeAdList.size() - 1) + nativeStep
} else nativeStep - 1
}

/**
* @param position index in wrapper adapter
* @return `true` if you can add [com.appodeal.ads.NativeAd] to this position
*/
private fun canUseThisPosition(position: Int): Boolean {
return nativeAdList[position] == null && itemCount > position
}

/**
* View holder for create custom [com.appodeal.ads.native_ad.views.NativeAdView]
*/
internal class NativeCustomAdViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {

private val nativeAdView: NativeAdView = itemView.findViewById(R.id.native_item)
private val tvTitle: TextView = itemView.findViewById(R.id.tv_title)
private val tvDescription: TextView = itemView.findViewById(R.id.tv_description)
private val ratingBar: RatingBar = itemView.findViewById(R.id.rb_rating)
private val ctaButton: Button = itemView.findViewById(R.id.b_cta)
private val nativeIconView: NativeIconView = itemView.findViewById(R.id.icon)
private val tvAgeRestrictions: TextView = itemView.findViewById(R.id.tv_age_restriction)
private val nativeMediaView: NativeMediaView = itemView.findViewById(R.id.appodeal_media_view_content)
private val providerViewContainer: FrameLayout = itemView.findViewById(R.id.provider_view)

fun fillNative(nativeAd: NativeAd?) {
tvTitle.text = nativeAd!!.title
tvDescription.text = nativeAd.description
if (nativeAd.rating == 0f) {
ratingBar.visibility = View.INVISIBLE
} else {
ratingBar.visibility = View.VISIBLE
ratingBar.rating = nativeAd.rating
ratingBar.stepSize = 0.1f
}
ctaButton.text = nativeAd.callToAction
val providerView = nativeAd.getProviderView(nativeAdView.context)
if (providerView != null) {
if (providerView.parent != null && providerView.parent is ViewGroup) {
(providerView.parent as ViewGroup).removeView(providerView)
}
providerViewContainer.removeAllViews()
val layoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.WRAP_CONTENT,
ViewGroup.LayoutParams.WRAP_CONTENT
)
providerViewContainer.addView(providerView, layoutParams)
}
if (nativeAd.ageRestrictions != null) {
tvAgeRestrictions.text = nativeAd.ageRestrictions
tvAgeRestrictions.visibility = View.VISIBLE
} else {
tvAgeRestrictions.visibility = View.GONE
}
if (nativeAd.containsVideo()) {
nativeAdView.nativeMediaView = nativeMediaView
} else {
nativeMediaView.visibility = View.GONE
}
nativeAdView.titleView = tvTitle
nativeAdView.descriptionView = tvDescription
nativeAdView.ratingView = ratingBar
nativeAdView.callToActionView = ctaButton
nativeAdView.setNativeIconView(nativeIconView)
nativeAdView.providerView = providerView
nativeAdView.registerView(nativeAd)
nativeAdView.visibility = View.VISIBLE
}

fun unregisterViewForInteraction() {
nativeAdView.unregisterViewForInteraction()
}
}

companion object {
private const val DEFAULT_NATIVE_STEP = 5
private const val VIEW_HOLDER_NATIVE_AD_TYPE = 600
}
}

To use this wrapper adapter, you should create a new instance ofAppodealWrapperAdapter:

val appodealWrapperAdapter: AppodealWrapperAdapter = AppodealWrapperAdapter(myAdapter, 2)

And set this wrapper adapter to your recycler view.

Common Mistakes

  • No ad attribution or AdChoices icon

The majority of ad networks require publishers to add a special mark to a native ad, so users don’t mistake them for content. That’s why you always need to make sure, that native ads in your app have the ad attribution (e.g., “Ad”) or the AdChoices icon.

  • Absence of the required native ad elements

Every native ad should contain:

  • title;

  • call-to-action button;

  • ad attribution or AdChoices icon;

  • icon, image or video.

  • Native ad elements alteration

Advertisers expect that their ads will be displayed clearly and without any alteration. You can scale buttons and images, but you shouldn't crop, cover or distort them.

  • Overlaying elements of native ads on each other

Make sure, that all elements of a native ad are visible and not overlaid.

Native ads requirements:

  • All of the fields of native ad marked as mandatory must be displayed.
  • Every ad should have a sign that clearly indicates that it is an ad. For example "Ad" or "Sponsored".
  • Image assets can be resized to fit your ad space but should not be significantly distorted or cropped.

Check If Ad Is Initialized

To check if native was initialized, you can use the method:

Appodeal.isInitialized(Appodeal.NATIVE)

Returns true, if the native was initialized.

Check If Autocache Is Enabled

To check if autocache is enabled for native, you can use the method:

Appodeal.isAutoCacheEnabled(Appodeal.NATIVE)

Returns true, if autocache is enabled for native.

Get Predicted eCPM

To get the predicted eCPM from the next block in the caching queue, use the method:

NativeAd.getPredictedEcpm()
tip

This method is reasonable to use if manual caching of ads is enabled.

Check Viewability

You can always check in logs if show was tracked and your ad is visible.

You will see the Native [Notify Shown] log if show was tracked successfully.

Appodeal  com.example.app  D Native [Notify Shown]