Native Ads - Ad Control Help Center

Overview

Native ads are an ad format that allows you to freely customize the ad UI to match your app’s design. You can provide a natural user experience by individually placing elements such as ad creatives (images, videos), headline, body, and CTA buttons.

Key Features

Complete UI Customization: Freely configure ad layout to match your app’s design system
Various Media Support: Image and video ad creative support
Flexible Click Area Settings: Full click or individual element click handling
Profile Information Display: Advertiser profile logo, name, and link support

Classes and Interfaces

AdropNativeAd

Main class for loading and managing native ads.

String

required

Ad unit ID (issued from console)

String

ID for contextual targeting (optional)

AdropNativeAdListener

Listener to handle ad events

Boolean

default:"false"

Whether to use custom click handling

Key Properties

Property	Type	Description
`headline`	`String`	Ad headline
`body`	`String`	Ad body text
`icon`	`String`	Icon image URL
`cover`	`String`	Cover image URL
`advertiser`	`String`	Deprecated. Use `profile.displayName` instead.
`advertiserURL`	`String`	Deprecated. Use `profile.link` instead.
`accountTag`	`JSONObject`	Deprecated. No longer supported.
`creativeTag`	`JSONObject`	Deprecated. No longer supported.
`callToAction`	`String`	Call-to-action text (e.g., “Learn More”)
`extraAssets`	`Map<String, AdropNativeAsset>`	Media items keyed by media ID. See Multi-Media Creatives
`profile`	`AdropNativeAdProfile`	Advertiser profile information
`isLoaded`	`Boolean`	Whether ad loading is complete
`isDestroyed`	`Boolean`	Whether ad is destroyed

AdropNativeAdView

Container view for displaying native ads.

Boolean

default:"false"

Whether to enable entire area click. When set to true, click events occur on the entire ad view area.

Key Methods

Method	Description
`setIconView(view, listener)`	Set icon image view (ImageView type)
`setHeadLineView(view, listener)`	Set headline text view (TextView type)
`setBodyView(view)`	Set body text view (TextView type)
`setMediaView(view)`	Set media container view (AdropMediaView type)
`setAdvertiserView(view, listener)`	Set advertiser text view (TextView type)
`setCallToActionView(view)`	Set CTA button or text view
`setProfileLogoView(view, listener)`	Set profile logo image view (ImageView type)
`setProfileNameView(view, listener)`	Set profile name text view (TextView type)
`setNativeAd(ad)`	Bind ad data to view
`destroy()`	Release resources

AdropMediaView

Media container view for displaying ad images or videos.

<io.adrop.ads.nativeAd.AdropMediaView
    android:id="@+id/ad_media"
    android:layout_width="match_parent"
    android:layout_height="200dp" />

For video creatives, AdropMediaView must be bound through AdropNativeAdView.setMediaView(...). Reading ad.asset and playing the URL with your own player (ExoPlayer, MediaPlayer, or any third-party library) bypasses the SDK’s video tracking pipeline, so VTR is not measured and onAdVideoStart / onAdVideoEnd never fire. See Video Tracking and VTR.

AdropNativeAdListener

Interface for handling ad events.

interface AdropNativeAdListener {
    fun onAdReceived(ad: AdropNativeAd)
    fun onAdClicked(ad: AdropNativeAd)
    fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode)
    fun onAdImpression(ad: AdropNativeAd) // Optional implementation
    fun onAdVideoStart(ad: AdropNativeAd) // Optional implementation
    fun onAdVideoEnd(ad: AdropNativeAd) // Optional implementation
}

AdropNativeAdProfile

Data class containing advertiser profile information.

Property	Type	Description
`displayLogo`	`String`	Profile logo image URL
`displayName`	`String`	Profile display name
`link`	`String`	Profile link URL

Implementation Guide

1. XML Layout Setup

Define the layout to display native ads. Use AdropNativeAdView as the root and place ad elements inside.

res/layout/native_ad_layout.xml

<?xml version="1.0" encoding="utf-8"?>
<io.adrop.ads.nativeAd.AdropNativeAdView
    android:id="@+id/native_ad_view"
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">

    <androidx.constraintlayout.widget.ConstraintLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:padding="16dp">

        <!-- Profile area -->
        <ImageView
            android:id="@+id/ad_profile_logo"
            android:layout_width="48dp"
            android:layout_height="48dp"
            android:scaleType="centerCrop"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintTop_toTopOf="parent" />

        <TextView
            android:id="@+id/ad_profile_name"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginStart="8dp"
            android:textSize="16sp"
            android:textStyle="bold"
            app:layout_constraintStart_toEndOf="@id/ad_profile_logo"
            app:layout_constraintTop_toTopOf="parent" />

        <TextView
            android:id="@+id/ad_badge"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginStart="8dp"
            android:layout_marginTop="4dp"
            android:text="Ad"
            android:textSize="12sp"
            app:layout_constraintStart_toEndOf="@id/ad_profile_logo"
            app:layout_constraintTop_toBottomOf="@id/ad_profile_name" />

        <!-- Media area -->
        <io.adrop.ads.nativeAd.AdropMediaView
            android:id="@+id/ad_media"
            android:layout_width="match_parent"
            android:layout_height="200dp"
            android:layout_marginTop="12dp"
            app:layout_constraintTop_toBottomOf="@id/ad_profile_logo" />

        <!-- Ad content -->
        <TextView
            android:id="@+id/ad_headline"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_marginTop="12dp"
            android:textSize="18sp"
            android:textStyle="bold"
            app:layout_constraintTop_toBottomOf="@id/ad_media" />

        <TextView
            android:id="@+id/ad_body"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_marginTop="8dp"
            android:textSize="14sp"
            app:layout_constraintTop_toBottomOf="@id/ad_headline" />

        <!-- Bottom area -->
        <TextView
            android:id="@+id/ad_advertiser"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_marginTop="12dp"
            android:textSize="14sp"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintTop_toBottomOf="@id/ad_body" />

        <Button
            android:id="@+id/ad_call_to_action"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            app:layout_constraintEnd_toEndOf="parent"
            app:layout_constraintTop_toBottomOf="@id/ad_body" />

    </androidx.constraintlayout.widget.ConstraintLayout>
</io.adrop.ads.nativeAd.AdropNativeAdView>

2. Load and Display Ad (Kotlin)

import android.os.Bundle
import android.util.Log
import android.widget.Button
import android.widget.ImageView
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import com.bumptech.glide.Glide
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.nativeAd.AdropMediaView
import io.adrop.ads.nativeAd.AdropNativeAd
import io.adrop.ads.nativeAd.AdropNativeAdListener
import io.adrop.ads.nativeAd.AdropNativeAdView

class NativeAdActivity : AppCompatActivity() {

    private lateinit var nativeAd: AdropNativeAd
    private lateinit var nativeAdView: AdropNativeAdView

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

        nativeAdView = findViewById(R.id.native_ad_view)
        loadNativeAd()
    }

    private fun loadNativeAd() {
        // 1. Create native ad instance
        nativeAd = AdropNativeAd(
            context = this,
            unitId = "YOUR_UNIT_ID"  // Replace with actual unit ID
        )

        // 2. Set listener
        nativeAd.listener = object : AdropNativeAdListener {
            override fun onAdReceived(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad received successfully")
                populateNativeAdView(ad)
            }

            override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
                Log.e("Adrop", "Ad failed to receive: $errorCode")
            }

            override fun onAdClicked(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad clicked")
            }

            override fun onAdImpression(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad impression")
            }

            override fun onAdVideoStart(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad video started")
            }

            override fun onAdVideoEnd(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad video ended")
            }
        }

        // 3. Load ad
        nativeAd.load()
    }

    private fun populateNativeAdView(ad: AdropNativeAd) {
        // Set profile
        val profileLogoView = findViewById<ImageView>(R.id.ad_profile_logo)
        Glide.with(this).load(ad.profile.displayLogo).into(profileLogoView)
        nativeAdView.setProfileLogoView(profileLogoView)

        val profileNameView = findViewById<TextView>(R.id.ad_profile_name)
        profileNameView.text = ad.profile.displayName
        nativeAdView.setProfileNameView(profileNameView)

        // Set headline
        val headlineView = findViewById<TextView>(R.id.ad_headline)
        headlineView.text = ad.headline
        nativeAdView.setHeadLineView(headlineView)

        // Set media
        val mediaView = findViewById<AdropMediaView>(R.id.ad_media)
        nativeAdView.setMediaView(mediaView)

        // Set body
        val bodyView = findViewById<TextView>(R.id.ad_body)
        bodyView.text = ad.body
        nativeAdView.setBodyView(bodyView)

        // Set advertiser
        val advertiserView = findViewById<TextView>(R.id.ad_advertiser)
        advertiserView.text = ad.profile.displayName
        nativeAdView.setAdvertiserView(advertiserView)

        // Set CTA button
        val ctaView = findViewById<Button>(R.id.ad_call_to_action)
        ctaView.text = ad.callToAction
        nativeAdView.setCallToActionView(ctaView)

        // Bind ad data
        nativeAdView.setNativeAd(ad)
    }

    override fun onDestroy() {
        // Release resources
        nativeAdView.destroy()
        nativeAd.destroy()
        super.onDestroy()
    }
}

import android.os.Bundle
import android.util.Log
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.widget.Button
import android.widget.ImageView
import android.widget.TextView
import androidx.fragment.app.Fragment
import com.bumptech.glide.Glide
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.nativeAd.AdropMediaView
import io.adrop.ads.nativeAd.AdropNativeAd
import io.adrop.ads.nativeAd.AdropNativeAdListener
import io.adrop.ads.nativeAd.AdropNativeAdView

class NativeAdFragment : Fragment() {

    private var nativeAd: AdropNativeAd? = null
    private var nativeAdView: AdropNativeAdView? = null

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        return inflater.inflate(R.layout.fragment_native_ad, container, false)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        nativeAdView = view.findViewById(R.id.native_ad_view)
        loadNativeAd()
    }

    private fun loadNativeAd() {
        nativeAd = AdropNativeAd(
            context = requireContext(),
            unitId = "YOUR_UNIT_ID"
        )

        nativeAd?.listener = object : AdropNativeAdListener {
            override fun onAdReceived(ad: AdropNativeAd) {
                populateNativeAdView(ad)
            }

            override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
                Log.e("Adrop", "Ad load failed: $errorCode")
            }

            override fun onAdClicked(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad clicked")
            }
        }

        nativeAd?.load()
    }

    private fun populateNativeAdView(ad: AdropNativeAd) {
        val view = requireView()

        // Profile logo
        val profileLogo = view.findViewById<ImageView>(R.id.ad_profile_logo)
        Glide.with(this).load(ad.profile.displayLogo).into(profileLogo)
        nativeAdView?.setProfileLogoView(profileLogo)

        // Profile name
        val profileName = view.findViewById<TextView>(R.id.ad_profile_name)
        profileName.text = ad.profile.displayName
        nativeAdView?.setProfileNameView(profileName)

        // Headline
        val headline = view.findViewById<TextView>(R.id.ad_headline)
        headline.text = ad.headline
        nativeAdView?.setHeadLineView(headline)

        // Media
        val media = view.findViewById<AdropMediaView>(R.id.ad_media)
        nativeAdView?.setMediaView(media)

        // Body
        val body = view.findViewById<TextView>(R.id.ad_body)
        body.text = ad.body
        nativeAdView?.setBodyView(body)

        // Advertiser
        val advertiser = view.findViewById<TextView>(R.id.ad_advertiser)
        advertiser.text = ad.profile.displayName
        nativeAdView?.setAdvertiserView(advertiser)

        // CTA
        val cta = view.findViewById<Button>(R.id.ad_call_to_action)
        cta.text = ad.callToAction
        nativeAdView?.setCallToActionView(cta)

        // Binding
        nativeAdView?.setNativeAd(ad)
    }

    override fun onDestroyView() {
        nativeAdView?.destroy()
        nativeAd?.destroy()
        super.onDestroyView()
    }
}

3. Load and Display Ad (Java)

Java

import android.os.Bundle;
import android.util.Log;
import android.widget.Button;
import android.widget.ImageView;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;
import com.bumptech.glide.Glide;
import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.nativeAd.AdropMediaView;
import io.adrop.ads.nativeAd.AdropNativeAd;
import io.adrop.ads.nativeAd.AdropNativeAdListener;
import io.adrop.ads.nativeAd.AdropNativeAdView;

public class NativeAdActivity extends AppCompatActivity {

    private AdropNativeAd nativeAd;
    private AdropNativeAdView nativeAdView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_native_ad);

        nativeAdView = findViewById(R.id.native_ad_view);
        loadNativeAd();
    }

    private void loadNativeAd() {
        // 1. Create native ad instance
        nativeAd = new AdropNativeAd(
            this,
            "YOUR_UNIT_ID",  // Replace with actual unit ID
            null  // contextId (optional)
        );

        // 2. Set listener
        nativeAd.setListener(new AdropNativeAdListener() {
            @Override
            public void onAdReceived(AdropNativeAd ad) {
                Log.d("Adrop", "Ad received successfully");
                populateNativeAdView(ad);
            }

            @Override
            public void onAdFailedToReceive(AdropNativeAd ad, AdropErrorCode errorCode) {
                Log.e("Adrop", "Ad failed to receive: " + errorCode);
            }

            @Override
            public void onAdClicked(AdropNativeAd ad) {
                Log.d("Adrop", "Ad clicked");
            }

            @Override
            public void onAdImpression(AdropNativeAd ad) {
                Log.d("Adrop", "Ad impression");
            }

            @Override
            public void onAdVideoStart(AdropNativeAd ad) {
                Log.d("Adrop", "Ad video started");
            }

            @Override
            public void onAdVideoEnd(AdropNativeAd ad) {
                Log.d("Adrop", "Ad video ended");
            }
        });

        // 3. Load ad
        nativeAd.load();
    }

    private void populateNativeAdView(AdropNativeAd ad) {
        // Set profile logo
        ImageView profileLogoView = findViewById(R.id.ad_profile_logo);
        Glide.with(this).load(ad.getProfile().getDisplayLogo()).into(profileLogoView);
        nativeAdView.setProfileLogoView(profileLogoView, null);

        // Set profile name
        TextView profileNameView = findViewById(R.id.ad_profile_name);
        profileNameView.setText(ad.getProfile().getDisplayName());
        nativeAdView.setProfileNameView(profileNameView, null);

        // Set headline
        TextView headlineView = findViewById(R.id.ad_headline);
        headlineView.setText(ad.getHeadline());
        nativeAdView.setHeadLineView(headlineView, null);

        // Set media
        AdropMediaView mediaView = findViewById(R.id.ad_media);
        nativeAdView.setMediaView(mediaView);

        // Set body
        TextView bodyView = findViewById(R.id.ad_body);
        bodyView.setText(ad.getBody());
        nativeAdView.setBodyView(bodyView);

        // Set advertiser
        TextView advertiserView = findViewById(R.id.ad_advertiser);
        advertiserView.setText(ad.getProfile().getDisplayName());
        nativeAdView.setAdvertiserView(advertiserView, null);

        // Set CTA button
        Button ctaView = findViewById(R.id.ad_call_to_action);
        ctaView.setText(ad.getCallToAction());
        nativeAdView.setCallToActionView(ctaView);

        // Bind ad data
        nativeAdView.setNativeAd(ad);
    }

    @Override
    protected void onDestroy() {
        // Release resources
        if (nativeAdView != null) {
            nativeAdView.destroy();
        }
        if (nativeAd != null) {
            nativeAd.destroy();
        }
        super.onDestroy();
    }
}

Advanced Features

Entire Click Area Setting

You can set the entire ad view area to trigger click events.

nativeAdView.isEntireClick = true

nativeAdView.setEntireClick(true);

When isEntireClick is set to true, the entire ad view becomes a clickable area. Individual element click listeners will not work.

Individual Element Click Listeners

You can set custom click listeners on specific ad elements.

// Custom action on advertiser click
nativeAdView.setAdvertiserView(advertiserView) {
    Log.d("Adrop", "Advertiser clicked")
    // Implement custom action
}

// Custom action on profile logo click
nativeAdView.setProfileLogoView(profileLogoView) {
    Log.d("Adrop", "Profile logo clicked")
    // Implement custom action
}

// Custom action on advertiser click
nativeAdView.setAdvertiserView(advertiserView, new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        Log.d("Adrop", "Advertiser clicked");
        // Implement custom action
    }
});

// Custom action on profile logo click
nativeAdView.setProfileLogoView(profileLogoView, new View.OnClickListener() {
    @Override
    public void onClick(View v) {
        Log.d("Adrop", "Profile logo clicked");
        // Implement custom action
    }
});

Contextual Targeting

You can request ads matching a specific context.

val nativeAd = AdropNativeAd(
    context = this,
    unitId = "YOUR_UNIT_ID",
    contextId = "SPORTS_NEWS"  // Context ID
)

AdropNativeAd nativeAd = new AdropNativeAd(
    this,
    "YOUR_UNIT_ID",
    "SPORTS_NEWS"  // Context ID
);

Using in RecyclerView

You can display native ads as items in a RecyclerView.

RecyclerView Adapter

class ContentAdapter : RecyclerView.Adapter<RecyclerView.ViewHolder>() {

    companion object {
        const val VIEW_TYPE_CONTENT = 0
        const val VIEW_TYPE_AD = 1
        const val AD_INTERVAL = 5  // Show ad every 5 items
    }

    private val items = mutableListOf<Any>()
    private val nativeAds = mutableMapOf<Int, AdropNativeAd>()

    override fun getItemViewType(position: Int): Int {
        return if (position % (AD_INTERVAL + 1) == AD_INTERVAL) {
            VIEW_TYPE_AD
        } else {
            VIEW_TYPE_CONTENT
        }
    }

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): RecyclerView.ViewHolder {
        return when (viewType) {
            VIEW_TYPE_AD -> {
                val view = LayoutInflater.from(parent.context)
                    .inflate(R.layout.item_native_ad, parent, false)
                NativeAdViewHolder(view)
            }
            else -> {
                val view = LayoutInflater.from(parent.context)
                    .inflate(R.layout.item_content, parent, false)
                ContentViewHolder(view)
            }
        }
    }

    override fun onBindViewHolder(holder: RecyclerView.ViewHolder, position: Int) {
        when (holder) {
            is NativeAdViewHolder -> loadNativeAd(holder, position)
            is ContentViewHolder -> holder.bind(items[position])
        }
    }

    private fun loadNativeAd(holder: NativeAdViewHolder, position: Int) {
        // Reuse already loaded ad
        nativeAds[position]?.let { ad ->
            if (ad.isLoaded) {
                holder.bind(ad)
                return
            }
        }

        // Load new ad
        val nativeAd = AdropNativeAd(holder.itemView.context, "YOUR_UNIT_ID")
        nativeAd.listener = object : AdropNativeAdListener {
            override fun onAdReceived(ad: AdropNativeAd) {
                nativeAds[position] = ad
                holder.bind(ad)
            }

            override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
                Log.e("Adrop", "Ad load failed: $errorCode")
            }

            override fun onAdClicked(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad clicked")
            }
        }
        nativeAd.load()
    }

    class NativeAdViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
        private val nativeAdView: AdropNativeAdView = itemView.findViewById(R.id.native_ad_view)

        fun bind(ad: AdropNativeAd) {
            val profileLogo = itemView.findViewById<ImageView>(R.id.ad_profile_logo)
            Glide.with(itemView.context).load(ad.profile.displayLogo).into(profileLogo)
            nativeAdView.setProfileLogoView(profileLogo)

            val profileName = itemView.findViewById<TextView>(R.id.ad_profile_name)
            profileName.text = ad.profile.displayName
            nativeAdView.setProfileNameView(profileName)

            val headline = itemView.findViewById<TextView>(R.id.ad_headline)
            headline.text = ad.headline
            nativeAdView.setHeadLineView(headline)

            val media = itemView.findViewById<AdropMediaView>(R.id.ad_media)
            nativeAdView.setMediaView(media)

            val body = itemView.findViewById<TextView>(R.id.ad_body)
            body.text = ad.body
            nativeAdView.setBodyView(body)

            val advertiser = itemView.findViewById<TextView>(R.id.ad_advertiser)
            advertiser.text = ad.profile.displayName
            nativeAdView.setAdvertiserView(advertiser)

            val cta = itemView.findViewById<Button>(R.id.ad_call_to_action)
            cta.text = ad.callToAction
            nativeAdView.setCallToActionView(cta)

            nativeAdView.setNativeAd(ad)
        }
    }

    fun destroy() {
        nativeAds.values.forEach { it.destroy() }
        nativeAds.clear()
    }
}

Test Unit IDs

Use the following test unit IDs during development and testing.

Format	Test Unit ID
Native (Image)	`PUBLIC_TEST_UNIT_ID_NATIVE`
Native Video (16:9)	`PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_16_9`
Native Video (9:16)	`PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_9_16`

Be sure to replace with actual unit IDs before production deployment.

Lifecycle Management

Resource Release in Activity/Fragment

Native ads must be released when no longer in use to prevent memory leaks.

override fun onDestroy() {
    nativeAdView.destroy()
    nativeAd.destroy()
    super.onDestroy()
}

override fun onDestroyView() {
    nativeAdView?.destroy()
    nativeAd?.destroy()
    super.onDestroyView()
}

@Override
protected void onDestroy() {
    if (nativeAdView != null) {
        nativeAdView.destroy();
    }
    if (nativeAd != null) {
        nativeAd.destroy();
    }
    super.onDestroy();
}

Resource Release in RecyclerView

When using ads in a RecyclerView Adapter, all ads must be released when the Activity or Fragment is destroyed.

override fun onDestroy() {
    adapter.destroy()
    super.onDestroy()
}

Video Tracking and VTR

Adrop measures video metrics for native creatives — including impression-to-completion (VTR), onAdVideoStart, and onAdVideoEnd — only when the video is rendered through the SDK’s media surface (AdropMediaView bound via AdropNativeAdView.setMediaView(...)). This applies to the ad’s main media (Media 1). For the other media items of a multi-media creative, see Multi-Media Creatives. The AdropNativeAd.asset property returns a URL pointing to the underlying image or video file. It is exposed as supplementary metadata (for example, for thumbnails or your own analytics); it is not intended to drive playback.

Do not feed the asset URL into a custom video player (ExoPlayer, MediaPlayer, or any third-party player) for a video native ad. When the SDK’s media surface is bypassed:

VTR (Video Through Rate) is not collected for that placement.
onAdVideoStart / onAdVideoEnd callbacks never fire.
Aggregate video performance for the unit will under-report or report zero.

Click (onAdClicked) and impression (onAdImpression) tracking still work because they are wired to the container view, but the video-specific signals are lost.

Recommended pattern

Bind the SDK media surface for every video native:

val mediaView = findViewById<AdropMediaView>(R.id.ad_media)
nativeAdView.setMediaView(mediaView)   // Required for video tracking
nativeAdView.setNativeAd(ad)

AdropMediaView mediaView = findViewById(R.id.ad_media);
nativeAdView.setMediaView(mediaView);   // Required for video tracking
nativeAdView.setNativeAd(ad);

If a placement absolutely requires a custom player and you accept that VTR will not be measured, you can still surface click and impression attribution by keeping the ad bound to AdropNativeAdView. In that case, treat the placement as non-VTR inventory in your internal reporting and avoid mixing it with SDK-measured video performance.

Multi-Media Creatives

Requires adrop-ads 1.16.0 or later. If you use backfill, update adrop-ads-backfill to the same version.

If a native unit has two or more media items, its creatives contain a file for each media item. extraAssets holds every media item of the ad, keyed by the media ID set in the console. Media 1 is always m1, and the other media items use the IDs shown in Media Size on the Ad Unit detail screen, such as m2 and m3.

val media2 = ad.extraAssets["m2"]   // AdropNativeAsset?

Media 1 (m1) is the same media as asset and creative. Keep displaying it with AdropMediaView, and draw only the other media items yourself.
extraAssets is empty for creatives of units with a single media item and for backfill ads. Display those ads as usual.
Look up media items by ID instead of relying on their order.
If the ad is served in dark mode, image media items are dark mode images too.
To check your layout with a multi-media creative, preview the creative on a test device.

AdropNativeAsset

Property	Type	Description
`id`	`String`	Media ID set in the console (e.g., `m1`, `m2`)
`asset`	`String`	Image or video file URL
`creative`	`String`	HTML that plays a video media item, including its tracking
`cover`	`String?`	Poster image URL of a video. `null` for images
`type`	`String?`	`"display"` (image) or `"video"`
`isVideo`	`Boolean`	Whether the media item is a video

Displaying Media Items

Media	Display	Placement
Image	Load `asset` into an `ImageView`	Inside `AdropNativeAdView`
Video	Load `creative` into a `WebView`	Outside `AdropNativeAdView`, e.g., right below it

Image: Set isEntireClick = true. Media items you draw aren’t views registered with the SDK, so in the default click mode a tap on them isn’t counted as a click. With entire click, if Media 1 is a video, taps on its player controls also count as ad clicks. Don’t load the creative HTML of an image: it doesn’t report clicks to Adrop.
Video: Play the creative HTML, not the asset URL. The HTML contains the video player and its tracking, so video metrics are measured only through it. Place the WebView outside AdropNativeAdView: inside, entire click turns every tap, including taps on the player’s controls, into an ad click. Load the HTML when the ad is about to appear on screen, not in advance.
Landing page: When a user taps the video, its HTML reports the click and asks to open the landing page in a new window or in the same window. With the default WebView settings, both requests arrive in shouldOverrideUrlLoading, so open the requested URL there.

Impressions and Clicks

Impressions, clicks, and video metrics are counted once per ad, not per media item, even when both the SDK and a media item report them.

Event	How it’s counted
Impression	When `AdropNativeAdView` stays at least 50% visible for 0.5 seconds. A video media item also reports the ad’s impression when its video starts playing.
Click inside `AdropNativeAdView`	Counted by the SDK, and `onAdClicked` is called.
Tap on a video media item	Reported by the media item’s HTML. `onAdClicked` isn’t called.
Video playback (Valid Views, Completed Views)	Reported by the media item’s HTML. `onAdVideoStart` and `onAdVideoEnd` aren’t called.

Which taps on a video count as clicks depends on the unit’s video controller setting. With the controller off, every tap on the video is a click. With it on, taps on the play and mute controls aren’t clicks.

Example

This example shows Media 2 (m2) as an image inside AdropNativeAdView, or as a video right below it. Replace m2 with the ID of your unit’s media item.

res/layout/native_multi_media_ad.xml

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

    <io.adrop.ads.nativeAd.AdropNativeAdView
        android:id="@+id/native_ad_view"
        android:layout_width="match_parent"
        android:layout_height="wrap_content">

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

            <TextView
                android:id="@+id/ad_headline"
                android:layout_width="match_parent"
                android:layout_height="wrap_content"
                android:textSize="18sp"
                android:textStyle="bold" />

            <!-- Media 1 (m1): drawn by the SDK -->
            <io.adrop.ads.nativeAd.AdropMediaView
                android:id="@+id/ad_media"
                android:layout_width="match_parent"
                android:layout_height="200dp"
                android:layout_marginTop="12dp" />

            <!-- Media 2 (m2) when it's an image -->
            <ImageView
                android:id="@+id/ad_media_2_image"
                android:layout_width="120dp"
                android:layout_height="120dp"
                android:layout_marginTop="12dp"
                android:scaleType="centerCrop"
                android:visibility="gone" />

            <Button
                android:id="@+id/ad_call_to_action"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:layout_marginTop="12dp" />
        </LinearLayout>
    </io.adrop.ads.nativeAd.AdropNativeAdView>

    <!-- Media 2 (m2) when it's a video: outside AdropNativeAdView -->
    <FrameLayout
        android:id="@+id/ad_media_2_video"
        android:layout_width="match_parent"
        android:layout_height="200dp"
        android:visibility="gone" />
</LinearLayout>

import android.annotation.SuppressLint
import android.content.ActivityNotFoundException
import android.content.Intent
import android.os.Bundle
import android.view.View
import android.view.ViewGroup
import android.webkit.WebResourceRequest
import android.webkit.WebView
import android.webkit.WebViewClient
import android.widget.Button
import android.widget.FrameLayout
import android.widget.ImageView
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import com.bumptech.glide.Glide
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.nativeAd.AdropMediaView
import io.adrop.ads.nativeAd.AdropNativeAd
import io.adrop.ads.nativeAd.AdropNativeAdListener
import io.adrop.ads.nativeAd.AdropNativeAdView
import io.adrop.ads.nativeAd.AdropNativeAsset

class MultiMediaNativeAdActivity : AppCompatActivity() {

    private lateinit var nativeAd: AdropNativeAd
    private lateinit var nativeAdView: AdropNativeAdView
    private var videoWebView: WebView? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.native_multi_media_ad)
        nativeAdView = findViewById(R.id.native_ad_view)

        nativeAd = AdropNativeAd(this, "YOUR_UNIT_ID")
        nativeAd.listener = object : AdropNativeAdListener {
            override fun onAdReceived(ad: AdropNativeAd) {
                populateNativeAdView(ad)
            }

            override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {}

            override fun onAdClicked(ad: AdropNativeAd) {}
        }
        nativeAd.load()
    }

    private fun populateNativeAdView(ad: AdropNativeAd) {
        // Count taps on the media items you draw as ad clicks
        nativeAdView.isEntireClick = true

        val headlineView = findViewById<TextView>(R.id.ad_headline)
        headlineView.text = ad.headline
        nativeAdView.setHeadLineView(headlineView)

        // Media 1 (m1) is drawn by the SDK
        nativeAdView.setMediaView(findViewById<AdropMediaView>(R.id.ad_media))

        val ctaView = findViewById<Button>(R.id.ad_call_to_action)
        ctaView.text = ad.callToAction
        nativeAdView.setCallToActionView(ctaView)

        // Media 2 (m2). Not in the map for single-media creatives and backfill ads
        ad.extraAssets["m2"]?.let { item ->
            if (item.isVideo) showVideo(item) else showImage(item)
        }

        nativeAdView.setNativeAd(ad)
    }

    private fun showImage(item: AdropNativeAsset) {
        val imageView = findViewById<ImageView>(R.id.ad_media_2_image)
        imageView.visibility = View.VISIBLE
        Glide.with(this).load(item.asset).into(imageView)
    }

    @SuppressLint("SetJavaScriptEnabled")
    private fun showVideo(item: AdropNativeAsset) {
        val webView = WebView(this).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true
            settings.mediaPlaybackRequiresUserGesture = false
            webViewClient = object : WebViewClient() {
                // A tap on the video: the HTML has reported the click and asks to open the landing page
                override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
                    try {
                        startActivity(Intent(Intent.ACTION_VIEW, request.url))
                    } catch (e: ActivityNotFoundException) {
                        // No app can open the URL
                    }
                    return true
                }
            }
            loadDataWithBaseURL(null, item.creative, "text/html", "UTF-8", null)
        }
        videoWebView = webView

        val container = findViewById<FrameLayout>(R.id.ad_media_2_video)
        container.visibility = View.VISIBLE
        container.addView(
            webView,
            FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)
        )
    }

    override fun onDestroy() {
        videoWebView?.let {
            (it.parent as? ViewGroup)?.removeView(it)
            it.destroy()
        }
        nativeAdView.destroy()
        nativeAd.destroy()
        super.onDestroy()
    }
}

import android.annotation.SuppressLint;
import android.content.ActivityNotFoundException;
import android.content.Intent;
import android.os.Bundle;
import android.view.View;
import android.view.ViewGroup;
import android.webkit.WebResourceRequest;
import android.webkit.WebView;
import android.webkit.WebViewClient;
import android.widget.Button;
import android.widget.FrameLayout;
import android.widget.ImageView;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;
import com.bumptech.glide.Glide;
import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.nativeAd.AdropMediaView;
import io.adrop.ads.nativeAd.AdropNativeAd;
import io.adrop.ads.nativeAd.AdropNativeAdListener;
import io.adrop.ads.nativeAd.AdropNativeAdView;
import io.adrop.ads.nativeAd.AdropNativeAsset;

public class MultiMediaNativeAdActivity extends AppCompatActivity {

    private AdropNativeAd nativeAd;
    private AdropNativeAdView nativeAdView;
    private WebView videoWebView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.native_multi_media_ad);
        nativeAdView = findViewById(R.id.native_ad_view);

        nativeAd = new AdropNativeAd(this, "YOUR_UNIT_ID", null);
        nativeAd.setListener(new AdropNativeAdListener() {
            @Override
            public void onAdReceived(AdropNativeAd ad) {
                populateNativeAdView(ad);
            }

            @Override
            public void onAdFailedToReceive(AdropNativeAd ad, AdropErrorCode errorCode) {}

            @Override
            public void onAdClicked(AdropNativeAd ad) {}
        });
        nativeAd.load();
    }

    private void populateNativeAdView(AdropNativeAd ad) {
        // Count taps on the media items you draw as ad clicks
        nativeAdView.setEntireClick(true);

        TextView headlineView = findViewById(R.id.ad_headline);
        headlineView.setText(ad.getHeadline());
        nativeAdView.setHeadLineView(headlineView, null);

        // Media 1 (m1) is drawn by the SDK
        AdropMediaView mediaView = findViewById(R.id.ad_media);
        nativeAdView.setMediaView(mediaView);

        Button ctaView = findViewById(R.id.ad_call_to_action);
        ctaView.setText(ad.getCallToAction());
        nativeAdView.setCallToActionView(ctaView);

        // Media 2 (m2). Not in the map for single-media creatives and backfill ads
        AdropNativeAsset item = ad.getExtraAssets().get("m2");
        if (item != null) {
            if (item.isVideo()) {
                showVideo(item);
            } else {
                showImage(item);
            }
        }

        nativeAdView.setNativeAd(ad);
    }

    private void showImage(AdropNativeAsset item) {
        ImageView imageView = findViewById(R.id.ad_media_2_image);
        imageView.setVisibility(View.VISIBLE);
        Glide.with(this).load(item.getAsset()).into(imageView);
    }

    @SuppressLint("SetJavaScriptEnabled")
    private void showVideo(AdropNativeAsset item) {
        WebView webView = new WebView(this);
        webView.getSettings().setJavaScriptEnabled(true);
        webView.getSettings().setDomStorageEnabled(true);
        webView.getSettings().setMediaPlaybackRequiresUserGesture(false);
        webView.setWebViewClient(new WebViewClient() {
            // A tap on the video: the HTML has reported the click and asks to open the landing page
            @Override
            public boolean shouldOverrideUrlLoading(WebView view, WebResourceRequest request) {
                try {
                    startActivity(new Intent(Intent.ACTION_VIEW, request.getUrl()));
                } catch (ActivityNotFoundException e) {
                    // No app can open the URL
                }
                return true;
            }
        });
        webView.loadDataWithBaseURL(null, item.getCreative(), "text/html", "UTF-8", null);
        videoWebView = webView;

        FrameLayout container = findViewById(R.id.ad_media_2_video);
        container.setVisibility(View.VISIBLE);
        container.addView(webView, new FrameLayout.LayoutParams(
            ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));
    }

    @Override
    protected void onDestroy() {
        if (videoWebView != null) {
            ViewGroup parent = (ViewGroup) videoWebView.getParent();
            if (parent != null) parent.removeView(videoWebView);
            videoWebView.destroy();
        }
        nativeAdView.destroy();
        nativeAd.destroy();
        super.onDestroy();
    }
}

In a RecyclerView, create the media item’s WebView when you bind the ad, and remove and destroy it in onViewRecycled().

Best Practices

1. Display Only Required Elements

You don’t need to display all ad elements. Selectively use only the elements needed to match your app’s design.

// Minimal configuration example (media + CTA only)
nativeAdView.setMediaView(mediaView)
nativeAdView.setCallToActionView(ctaView)
nativeAdView.setNativeAd(ad)

2. Use Image Loading Libraries

Use image loading libraries like Glide or Coil when displaying icon, cover, and profile images.

// Glide example
Glide.with(context)
    .load(ad.icon)
    .placeholder(R.drawable.placeholder)
    .error(R.drawable.error)
    .into(iconView)

3. Reuse Ad Views

When displaying ads in a RecyclerView, cache and reuse ad instances.

4. Appropriate Ad Placement

Place ads naturally without degrading user experience.

Content feed: 1 ad every 5-10 items
Detail screen: Place at bottom of content
Scroll view: Place to match natural content flow

5. Error Handling

Implement appropriate fallback handling for ad load failures.

override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
    when (errorCode) {
        AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
            // No ad available - hide ad area
            nativeAdView.visibility = View.GONE
        }
        AdropErrorCode.ERROR_CODE_NETWORK -> {
            // Network error - retry logic
            Handler(Looper.getMainLooper()).postDelayed({
                nativeAd.load()
            }, 3000)
        }
        else -> {
            Log.e("Adrop", "Ad load failed: $errorCode")
        }
    }
}

Complete Example

import android.os.Bundle
import android.util.Log
import android.view.View
import android.widget.Button
import android.widget.ImageView
import android.widget.TextView
import androidx.appcompat.app.AppCompatActivity
import com.bumptech.glide.Glide
import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.nativeAd.AdropMediaView
import io.adrop.ads.nativeAd.AdropNativeAd
import io.adrop.ads.nativeAd.AdropNativeAdListener
import io.adrop.ads.nativeAd.AdropNativeAdView

class NativeAdExampleActivity : AppCompatActivity() {

    private lateinit var nativeAd: AdropNativeAd
    private lateinit var nativeAdView: AdropNativeAdView
    private lateinit var loadingView: View
    private lateinit var errorView: View

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

        nativeAdView = findViewById(R.id.native_ad_view)
        loadingView = findViewById(R.id.loading_view)
        errorView = findViewById(R.id.error_view)

        findViewById<Button>(R.id.retry_button).setOnClickListener {
            loadNativeAd()
        }

        loadNativeAd()
    }

    private fun loadNativeAd() {
        showLoading()

        nativeAd = AdropNativeAd(
            context = this,
            unitId = "PUBLIC_TEST_UNIT_ID_NATIVE"
        )

        nativeAd.listener = object : AdropNativeAdListener {
            override fun onAdReceived(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad received: unitId=${ad.unitId}, txId=${ad.txId}")
                populateNativeAdView(ad)
                showAd()
            }

            override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
                Log.e("Adrop", "Ad failed to receive: $errorCode")
                showError()
            }

            override fun onAdClicked(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad clicked: txId=${ad.txId}")
            }

            override fun onAdImpression(ad: AdropNativeAd) {
                Log.d("Adrop", "Ad impression: txId=${ad.txId}")
            }
        }

        nativeAd.load()
    }

    private fun populateNativeAdView(ad: AdropNativeAd) {
        // Enable entire click area (optional)
        // nativeAdView.isEntireClick = true

        // Profile logo
        val profileLogoView = findViewById<ImageView>(R.id.ad_profile_logo)
        Glide.with(this)
            .load(ad.profile.displayLogo)
            .circleCrop()
            .into(profileLogoView)
        nativeAdView.setProfileLogoView(profileLogoView)

        // Profile name
        val profileNameView = findViewById<TextView>(R.id.ad_profile_name)
        profileNameView.text = ad.profile.displayName
        nativeAdView.setProfileNameView(profileNameView)

        // Headline
        val headlineView = findViewById<TextView>(R.id.ad_headline)
        headlineView.text = ad.headline
        nativeAdView.setHeadLineView(headlineView)

        // Media (image or video)
        val mediaView = findViewById<AdropMediaView>(R.id.ad_media)
        nativeAdView.setMediaView(mediaView)

        // Body
        val bodyView = findViewById<TextView>(R.id.ad_body)
        bodyView.text = ad.body
        nativeAdView.setBodyView(bodyView)

        // Advertiser
        val advertiserView = findViewById<TextView>(R.id.ad_advertiser)
        advertiserView.text = ad.profile.displayName
        nativeAdView.setAdvertiserView(advertiserView) {
            Log.d("Adrop", "Advertiser clicked: ${ad.profile.displayName}")
        }

        // CTA button
        val ctaView = findViewById<Button>(R.id.ad_call_to_action)
        ctaView.text = ad.callToAction
        nativeAdView.setCallToActionView(ctaView)

        // Bind ad data
        nativeAdView.setNativeAd(ad)
    }

    private fun showLoading() {
        loadingView.visibility = View.VISIBLE
        nativeAdView.visibility = View.GONE
        errorView.visibility = View.GONE
    }

    private fun showAd() {
        loadingView.visibility = View.GONE
        nativeAdView.visibility = View.VISIBLE
        errorView.visibility = View.GONE
    }

    private fun showError() {
        loadingView.visibility = View.GONE
        nativeAdView.visibility = View.GONE
        errorView.visibility = View.VISIBLE
    }

    override fun onDestroy() {
        nativeAdView.destroy()
        nativeAd.destroy()
        super.onDestroy()
    }
}

import android.os.Bundle;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.ImageView;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;
import com.bumptech.glide.Glide;
import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.nativeAd.AdropMediaView;
import io.adrop.ads.nativeAd.AdropNativeAd;
import io.adrop.ads.nativeAd.AdropNativeAdListener;
import io.adrop.ads.nativeAd.AdropNativeAdView;

public class NativeAdExampleActivity extends AppCompatActivity {

    private AdropNativeAd nativeAd;
    private AdropNativeAdView nativeAdView;
    private View loadingView;
    private View errorView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_native_ad_example);

        nativeAdView = findViewById(R.id.native_ad_view);
        loadingView = findViewById(R.id.loading_view);
        errorView = findViewById(R.id.error_view);

        findViewById(R.id.retry_button).setOnClickListener(v -> loadNativeAd());

        loadNativeAd();
    }

    private void loadNativeAd() {
        showLoading();

        nativeAd = new AdropNativeAd(
            this,
            "PUBLIC_TEST_UNIT_ID_NATIVE",
            null
        );

        nativeAd.setListener(new AdropNativeAdListener() {
            @Override
            public void onAdReceived(AdropNativeAd ad) {
                Log.d("Adrop", "Ad received: unitId=" + ad.getUnitId() + ", txId=" + ad.getTxId());
                populateNativeAdView(ad);
                showAd();
            }

            @Override
            public void onAdFailedToReceive(AdropNativeAd ad, AdropErrorCode errorCode) {
                Log.e("Adrop", "Ad failed to receive: " + errorCode);
                showError();
            }

            @Override
            public void onAdClicked(AdropNativeAd ad) {
                Log.d("Adrop", "Ad clicked: txId=" + ad.getTxId());
            }

            @Override
            public void onAdImpression(AdropNativeAd ad) {
                Log.d("Adrop", "Ad impression: txId=" + ad.getTxId());
            }
        });

        nativeAd.load();
    }

    private void populateNativeAdView(AdropNativeAd ad) {
        // Profile logo
        ImageView profileLogoView = findViewById(R.id.ad_profile_logo);
        Glide.with(this)
            .load(ad.getProfile().getDisplayLogo())
            .circleCrop()
            .into(profileLogoView);
        nativeAdView.setProfileLogoView(profileLogoView, null);

        // Profile name
        TextView profileNameView = findViewById(R.id.ad_profile_name);
        profileNameView.setText(ad.getProfile().getDisplayName());
        nativeAdView.setProfileNameView(profileNameView, null);

        // Headline
        TextView headlineView = findViewById(R.id.ad_headline);
        headlineView.setText(ad.getHeadline());
        nativeAdView.setHeadLineView(headlineView, null);

        // Media
        AdropMediaView mediaView = findViewById(R.id.ad_media);
        nativeAdView.setMediaView(mediaView);

        // Body
        TextView bodyView = findViewById(R.id.ad_body);
        bodyView.setText(ad.getBody());
        nativeAdView.setBodyView(bodyView);

        // Advertiser
        TextView advertiserView = findViewById(R.id.ad_advertiser);
        advertiserView.setText(ad.getProfile().getDisplayName());
        nativeAdView.setAdvertiserView(advertiserView, v -> {
            Log.d("Adrop", "Advertiser clicked: " + ad.getProfile().getDisplayName());
        });

        // CTA button
        Button ctaView = findViewById(R.id.ad_call_to_action);
        ctaView.setText(ad.getCallToAction());
        nativeAdView.setCallToActionView(ctaView);

        // Bind ad data
        nativeAdView.setNativeAd(ad);
    }

    private void showLoading() {
        loadingView.setVisibility(View.VISIBLE);
        nativeAdView.setVisibility(View.GONE);
        errorView.setVisibility(View.GONE);
    }

    private void showAd() {
        loadingView.setVisibility(View.GONE);
        nativeAdView.setVisibility(View.VISIBLE);
        errorView.setVisibility(View.GONE);
    }

    private void showError() {
        loadingView.setVisibility(View.GONE);
        nativeAdView.setVisibility(View.GONE);
        errorView.setVisibility(View.VISIBLE);
    }

    @Override
    protected void onDestroy() {
        if (nativeAdView != null) {
            nativeAdView.destroy();
        }
        if (nativeAd != null) {
            nativeAd.destroy();
        }
        super.onDestroy();
    }
}

Batch Loading (loads)

Use AdropNativeAd.loads() to request multiple native ads in a single batched call. This is useful for prefetching a pool of ads to insert into feeds, carousels, or paginated lists.

Signature

AdropNativeAd.loads(
    context: Context,
    unitId: String,
    contextId: String? = null,
    listener: AdropNativeAdListener,
)

AdropNativeAd.loads(context, "YOUR_UNIT_ID", null, listener);

Usage

AdropNativeAd.loads(
    context = this,
    unitId = "YOUR_UNIT_ID",
    contextId = null,
    listener = object : AdropNativeAdListener {
        // Batch success — each ad is fully rendered and ready to bind.
        override fun onAdsReceived(ads: List<AdropNativeAd>) {
            ads.forEach { ad ->
                // Bind to an AdropNativeAdView or store for later lifecycle.
                bindToView(ad)
            }
        }

        // Batch failure
        override fun onAdsFailedToReceive(errorCode: AdropErrorCode) {
            Log.e("Adrop", "Batch load failed: $errorCode")
        }

        // Single-load callbacks are NOT invoked on this path.
        override fun onAdReceived(ad: AdropNativeAd) { /* batch path */ }
        override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {}

        // Click / impression / video callbacks still fire per instance.
        override fun onAdClicked(ad: AdropNativeAd) {
            Log.d("Adrop", "Native clicked: ${ad.creativeId}")
        }

        override fun onAdImpression(ad: AdropNativeAd) {
            Log.d("Adrop", "Native impression: ${ad.creativeId}")
        }
    },
)

AdropNativeAd.loads(this, "YOUR_UNIT_ID", null, new AdropNativeAdListener() {
    @Override
    public void onAdsReceived(@NotNull List<AdropNativeAd> ads) {
        for (AdropNativeAd ad : ads) {
            bindToView(ad);
        }
    }

    @Override
    public void onAdsFailedToReceive(@NotNull AdropErrorCode errorCode) {
        Log.e("Adrop", "Batch load failed: " + errorCode);
    }

    @Override
    public void onAdReceived(@NotNull AdropNativeAd ad) { }

    @Override
    public void onAdFailedToReceive(@NotNull AdropNativeAd ad, @NotNull AdropErrorCode errorCode) { }

    @Override
    public void onAdClicked(@NotNull AdropNativeAd ad) {
        Log.d("Adrop", "Native clicked: " + ad.getCreativeId());
    }

    @Override
    public void onAdImpression(@NotNull AdropNativeAd ad) {
        Log.d("Adrop", "Native impression: " + ad.getCreativeId());
    }
});

Listener Callbacks

Callback	When it fires
`onAdsReceived(ads)`	Batch delivered. Every ad is fully rendered — creative is ready to bind.
`onAdsFailedToReceive(errorCode)`	Request rejected, network failure, or no fillable ads were returned (`ERROR_CODE_AD_NO_FILL`).
`onAdClicked` / `onAdImpression` / `onAdVideoStart` / `onAdVideoEnd`	Fire on each returned ad just like a single `load()`.

The singular onAdReceived / onAdFailedToReceive callbacks are not invoked on the loads() path. Use onAdsReceived / onAdsFailedToReceive as the sole batch signals.

Constraints

Maximum 5 ads per call. If the server returns more, only the first 5 are delivered.
Backfill is not applied. If no direct ads fill, onAdsFailedToReceive is called with ERROR_CODE_AD_NO_FILL regardless of backfill configuration.
Do not call destroy() inside onAdsReceived. Bind each ad to an AdropNativeAdView via setNativeAd(...) or store for later lifecycle, then destroy() on the parent Activity.onDestroy() (or equivalent).
Unlike AdropBanner.loads(), the native batch waits for every returned ad to finish rendering before firing onAdsReceived, so each instance is fully rendered on delivery.

Backfill Ads

When backfill ads are enabled, backfill ads are automatically loaded when direct ads are unavailable. Use the isBackfilled property to check if the ad is a backfill ad.

nativeAd.listener = object : AdropNativeAdListener {
    override fun onAdReceived(ad: AdropNativeAd) {
        if (ad.isBackfilled) {
            println("Backfill ad loaded")
        } else {
            println("Direct ad loaded")
        }
    }

    override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {
        when (errorCode) {
            AdropErrorCode.ERROR_CODE_AD_NO_FILL -> {
                println("No direct ad, requesting backfill...")
            }
            AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL -> {
                println("Backfill ad also not available")
            }
            else -> {
                println("Ad load failed: $errorCode")
            }
        }
    }
}

nativeAd.setListener(new AdropNativeAdListener() {
    @Override
    public void onAdReceived(AdropNativeAd ad) {
        if (ad.isBackfilled()) {
            System.out.println("Backfill ad loaded");
        } else {
            System.out.println("Direct ad loaded");
        }
    }

    @Override
    public void onAdFailedToReceive(AdropNativeAd ad, AdropErrorCode errorCode) {
        if (errorCode == AdropErrorCode.ERROR_CODE_AD_NO_FILL) {
            System.out.println("No direct ad, requesting backfill...");
        } else if (errorCode == AdropErrorCode.ERROR_CODE_AD_BACKFILL_NO_FILL) {
            System.out.println("Backfill ad also not available");
        } else {
            System.out.println("Ad load failed: " + errorCode);
        }
    }
});

AdChoices Position

For backfill native ads, you can choose which corner displays the AdChoices badge. Set preferredAdChoicesPosition on the AdropNativeAd instance before calling load().

import io.adrop.ads.nativeAd.AdropAdChoicesPosition
import io.adrop.ads.nativeAd.AdropNativeAd

val nativeAd = AdropNativeAd(this, "YOUR_UNIT_ID")
nativeAd.preferredAdChoicesPosition = AdropAdChoicesPosition.BOTTOM_RIGHT
nativeAd.load()

import io.adrop.ads.nativeAd.AdropAdChoicesPosition;
import io.adrop.ads.nativeAd.AdropNativeAd;

AdropNativeAd nativeAd = new AdropNativeAd(this, "YOUR_UNIT_ID");
nativeAd.setPreferredAdChoicesPosition(AdropAdChoicesPosition.BOTTOM_RIGHT);
nativeAd.load();

Value	Description
`AdropAdChoicesPosition.TOP_LEFT`	Top-left corner
`AdropAdChoicesPosition.TOP_RIGHT`	Top-right corner (default)
`AdropAdChoicesPosition.BOTTOM_LEFT`	Bottom-left corner
`AdropAdChoicesPosition.BOTTOM_RIGHT`	Bottom-right corner

This setting is a preferred hint for the backfill network and applies only to backfill native ads — direct ads are not affected. The value must be set before load() is called. The backfill network may override the position depending on its policy.

To use backfill ads, add the io.adrop:adrop-ads-backfill dependency. See Getting Started.

Preloading Backfill Ads (preload)

Starting with SDK 1.17.0, you can use AdropNativeAd.preload() to preload a backfill native ad. When a native ad that you load() with the same unit ID and the same AdChoices position gets no direct ad and falls back to a backfill ad, it uses the preloaded ad right away instead of requesting a backfill ad again. load() still requests a direct ad first, regardless of preload. If a direct ad is received, the preloaded ad is kept as is. If you don’t call preload, the behavior is the same as before.

Requirements

Both io.adrop:adrop-ads and io.adrop:adrop-ads-backfill must be 1.17.0 or later.
Preload fetches a backfill ad only when the server has told the app that there are no direct ads to show right now. Otherwise, it ends with ERROR_CODE_AD_PRELOAD_SKIPPED without requesting a backfill ad. This is a normal result in apps that have direct ad campaigns.
Right after the app is installed, right after you change the App Key, and right after you switch to a different user with setUID, preload ends with ERROR_CODE_AD_PRELOAD_SKIPPED until the server response arrives.
With test unit IDs, preload always ends with ERROR_CODE_AD_PRELOAD_SKIPPED.

Usage

Pass the Activity that will display the ad as context, and call preload right before you open the screen that contains the native ad. A preloaded ad is discarded after 30 minutes if it isn’t used, so call preload only for ads you’re about to display. You don’t need to wait for the result before calling load(). If the ad is still being fetched, load() waits for that result and uses it.

import io.adrop.ads.model.AdropErrorCode
import io.adrop.ads.nativeAd.AdropAdChoicesPosition
import io.adrop.ads.nativeAd.AdropNativeAd
import io.adrop.ads.nativeAd.AdropNativeAdListener

AdropNativeAd.preload(
    context = this, // Activity that will display the ad
    unitId = "YOUR_UNIT_ID",
    preferredAdChoicesPosition = AdropAdChoicesPosition.TOP_RIGHT, // Default
    listener = object : AdropNativeAdListener {
        override fun onAdPreloadReceived(unitId: String, contextId: String?) {
            println("Preload complete: $unitId")
        }

        override fun onAdPreloadFailedToReceive(unitId: String, contextId: String?, errorCode: AdropErrorCode) {
            // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
            // Don't call preload again right away here.
            println("Not preloaded: $errorCode")
        }

        // Not called for preload.
        override fun onAdReceived(ad: AdropNativeAd) {}
        override fun onAdClicked(ad: AdropNativeAd) {}
        override fun onAdFailedToReceive(ad: AdropNativeAd, errorCode: AdropErrorCode) {}
    },
)

import io.adrop.ads.model.AdropErrorCode;
import io.adrop.ads.nativeAd.AdropAdChoicesPosition;
import io.adrop.ads.nativeAd.AdropNativeAd;
import io.adrop.ads.nativeAd.AdropNativeAdListener;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

AdropNativeAd.preload(this, "YOUR_UNIT_ID", null, AdropAdChoicesPosition.TOP_RIGHT, new AdropNativeAdListener() {
    @Override
    public void onAdPreloadReceived(@NotNull String unitId, @Nullable String contextId) {
        System.out.println("Preload complete: " + unitId);
    }

    @Override
    public void onAdPreloadFailedToReceive(@NotNull String unitId, @Nullable String contextId, @NotNull AdropErrorCode errorCode) {
        // ERROR_CODE_AD_PRELOAD_SKIPPED is a normal result.
        // Don't call preload again right away here.
        System.out.println("Not preloaded: " + errorCode);
    }

    // Not called for preload.
    @Override
    public void onAdReceived(@NotNull AdropNativeAd ad) { }

    @Override
    public void onAdClicked(@NotNull AdropNativeAd ad) { }

    @Override
    public void onAdFailedToReceive(@NotNull AdropNativeAd ad, @NotNull AdropErrorCode errorCode) { }
});

To use the preloaded ad, set the preferredAdChoicesPosition of the AdropNativeAd you load() to the same value you passed to preload. Both default to TOP_RIGHT.

val nativeAd = AdropNativeAd(this, "YOUR_UNIT_ID")
nativeAd.preferredAdChoicesPosition = AdropAdChoicesPosition.TOP_RIGHT // Value passed to preload
nativeAd.load()

AdropNativeAd nativeAd = new AdropNativeAd(this, "YOUR_UNIT_ID");
nativeAd.setPreferredAdChoicesPosition(AdropAdChoicesPosition.TOP_RIGHT); // Value passed to preload
nativeAd.load();

When a Preloaded Ad Is Used

Same unit ID and same AdChoices position: The AdChoices position is fixed when the backfill ad is fetched, so the preferredAdChoicesPosition of the ad you load() must match the value you passed to preload. If it differs, the preloaded ad is kept as is, and load() requests a backfill ad as usual.
Same Activity: A preloaded ad isn’t used by an AdropNativeAd created with a different Activity from the one you passed to preload (for example, if you preload in a splash Activity and call load() in the main Activity). When the Activity you passed to preload finishes, the preloaded ad is discarded as well.
Used only once: A preloaded ad is gone once a single load() uses it. To preload again, call preload again.
Lifetime and count: An ad that isn’t used within 30 minutes is discarded. Only 1 ad is kept per unit and AdChoices position, and native ads keep up to 5 different combinations. When there are more than 5, ads are discarded starting with the one received first.
Calling again: Calling preload again with the same unit and AdChoices position doesn’t make a new request. If an ad has already been preloaded, onAdPreloadReceived is called without a new request; if one is still being fetched, you get that load’s result (success or failure). You can’t use preload to refresh an ad. However, if the user consent status has changed in the meantime, or if you call it with a different Activity, the existing ad is discarded and a new one is fetched.
Consent status changes: If the user consent status changes after an ad is preloaded, that ad isn’t used by load().

Result Callbacks

The following callbacks have been added to AdropNativeAdListener. Both are optional to implement, and each time you call preload, one of the two is called once on the main thread. No other listener callbacks are called for preload.

Callback	When it fires
`onAdPreloadReceived(unitId, contextId)`	When preloading has finished. A `load()` that was waiting for that result may have already used the ad.
`onAdPreloadFailedToReceive(unitId, contextId, errorCode)`	When the ad couldn’t be preloaded

contextId returns the value you passed to preload as is. It isn’t used to select a preloaded ad.

Failure Codes

Error Code	Description
`ERROR_CODE_AD_PRELOAD_SKIPPED`	No backfill ad was requested because direct ads may be shown, or because that hasn’t been confirmed yet. This is a normal result, so call preload again right before you open the next screen.
`ERROR_CODE_AD_NO_FILL`	The backfill dependency (1.17.0 or later) is missing, backfill isn’t configured for the unit, or the SDK hasn’t received that configuration yet. Call preload again a little later. If the backfill dependency is missing, preload keeps ending with this code.
`ERROR_CODE_AD_BACKFILL_NO_FILL`	No backfill ad is available.
`ERROR_CODE_INTERNAL`	The request was interrupted (for example, the Activity you passed to preload finished while the ad was being fetched) or an internal error occurred. Call preload again later.
`ERROR_CODE_INITIALIZE`	The SDK isn’t initialized. Preload also ends with this code on devices that aren’t in the target countries of `Adrop.initialize()`.
`ERROR_CODE_INVALID_UNIT`	The unit ID is empty.

Don’t call preload again right away inside the failure callback. If the result doesn’t change — for example, when the backfill dependency is missing — the calls repeat endlessly. Call it again later, such as before you open the next screen.

Next Steps

Banner Ads

Implement banner ads

Interstitial Ads

Implement interstitial ads

Targeting Settings

User properties and context targeting

Reference

Classes, listeners, error codes

​Overview

​Key Features

​Classes and Interfaces

​AdropNativeAd

​Key Properties

​AdropNativeAdView

​Key Methods

​AdropMediaView

​AdropNativeAdListener

​AdropNativeAdProfile

​Implementation Guide

​1. XML Layout Setup

​2. Load and Display Ad (Kotlin)

​3. Load and Display Ad (Java)

​Advanced Features

​Entire Click Area Setting

​Individual Element Click Listeners

​Contextual Targeting

​Using in RecyclerView

​Test Unit IDs

​Lifecycle Management

​Resource Release in Activity/Fragment

​Resource Release in RecyclerView

​Video Tracking and VTR

​Recommended pattern

​Multi-Media Creatives

​AdropNativeAsset

​Displaying Media Items

​Impressions and Clicks

​Example

​Best Practices

​1. Display Only Required Elements

​2. Use Image Loading Libraries

​3. Reuse Ad Views

​4. Appropriate Ad Placement

​5. Error Handling

​Complete Example

​Batch Loading (loads)

​Signature

​Usage

​Listener Callbacks

​Constraints

​Backfill Ads

​AdChoices Position

​Preloading Backfill Ads (preload)

​Requirements

​Usage

​When a Preloaded Ad Is Used

​Result Callbacks

​Failure Codes

​Next Steps

Banner Ads

Interstitial Ads

Targeting Settings

Reference

Overview

Key Features

Classes and Interfaces

AdropNativeAd

Key Properties

AdropNativeAdView

Key Methods

AdropMediaView

AdropNativeAdListener

AdropNativeAdProfile

Implementation Guide

1. XML Layout Setup

2. Load and Display Ad (Kotlin)

3. Load and Display Ad (Java)

Advanced Features

Entire Click Area Setting

Individual Element Click Listeners

Contextual Targeting

Using in RecyclerView

Test Unit IDs

Lifecycle Management

Resource Release in Activity/Fragment

Resource Release in RecyclerView

Video Tracking and VTR

Recommended pattern

Multi-Media Creatives

AdropNativeAsset

Displaying Media Items

Impressions and Clicks

Example

Best Practices

1. Display Only Required Elements

2. Use Image Loading Libraries

3. Reuse Ad Views

4. Appropriate Ad Placement

5. Error Handling

Complete Example

Batch Loading (loads)

Signature

Usage

Listener Callbacks

Constraints

Backfill Ads

AdChoices Position

Preloading Backfill Ads (preload)

Requirements

Usage

When a Preloaded Ad Is Used

Result Callbacks

Failure Codes

Next Steps