Skip to main content

Overview

Native ads are an ad format that allows you to freely customize the ad UI to match your app’s design. You can individually place ad elements such as media (images, videos), title, description, and CTA button to provide a natural user experience.

Key Features

  • Complete UI Customization: Freely configure ad layout to match your app’s design system
  • Support for Various Media: Support for image and video ad materials
  • Flexible Click Handling: Full click or custom click handling available
  • Profile Information Display: Support for advertiser profile logo and name
  • Backfill Ad Support: Can check if it’s a backfill ad

AdropNativeAd Class

The main class for loading and managing native ads.

Constructor

string
required
Ad unit ID (issued from console)
boolean
default:"false"
Whether to use custom click handling
  • true: Developer implements click handling directly (can use video ad controller)
  • false: AdropNativeAdView automatically handles all click events
AdropAdChoicesPosition
default:"AdropAdChoicesPosition.topRight"
AdChoices badge position for backfill native ads

Methods

Properties


AdropNativeAdView Component

Container component to display native ads.

Props

AdropNativeAd
Native ad instance to display

Usage Example

AdropNativeAdView provides ad context, so all ad element views must be placed inside this component.

Native Ad Element Views

AdropProfileLogoView

Image component to display advertiser profile logo.
Props: Omit<ImageProps, 'source'> (React Native Image component properties, source is auto-populated)

AdropProfileNameView

Text component to display advertiser profile name.
Props: TextProps (React Native Text component properties)

AdropHeadLineView

Text component to display ad title.
Props: TextProps (React Native Text component properties)

AdropBodyView

Text component to display ad body text.
Props: TextProps (React Native Text component properties)

AdropMediaView

Media component to display ad image or video.
Props: ViewProps (React Native View component properties)
For video native creatives, render properties.creative (the HTML payload) inside a WebView. Passing properties.asset directly into react-native-video or any other custom player bypasses the SDK’s video tracking pipeline, so VTR is not measured and onAdVideoStart / onAdVideoEnd never fire. See Video Tracking and VTR.

AdropCallToActionView

Text component to display call-to-action (CTA) message.
Props: TextProps (React Native Text component properties)

AdropAdvertiserView

Text component to display advertiser name.
Props: TextProps (React Native Text component properties)

AdropIconView

Image component to display ad icon.
Props: Omit<ImageProps, 'source'> (React Native Image component properties, source is auto-populated)

AdropNativeAdListener Interface

Listener interface for handling ad events.

AdropNativeProperties Type

Type containing ad properties information.

AdropNativeProfile Type

Type containing advertiser profile information.

Implementation Example

Here’s a complete example of implementing native ads.

Test Unit IDs

Use the following test unit IDs during development and testing.
Be sure to replace with actual unit IDs before production deployment.

Error Handling

When ad loading fails, you can receive error codes in the onAdFailedToReceive callback.

Common Error Codes

Error Handling Example


Best Practices

1. Resource Cleanup

Always release ad resources when component unmounts.

2. Video Ad and Backfill Ad Handling

Choose appropriate rendering method based on whether it’s a video ad or backfill ad.

3. URL Handling

Handle URL clicks in WebView to open in external browser.

4. Selective Use of Ad Elements

Selectively use only the ad elements needed to match your app’s design.

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. On React Native, that means rendering the HTML creative (properties.creative) inside a WebView, as shown in the Implementation Example. 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 properties.asset field 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 properties.asset URL into a custom video player (react-native-video, expo-av, 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 AdropNativeAdView, but the video-specific signals are lost.
For video creatives, render the HTML creative inside a WebView placed inside AdropNativeAdView:
The isVideoAd and isBackfilled flags on AdropNativeAd let you branch between <AdropMediaView /> (image or backfill creative) and <WebView /> (direct video creative) without inspecting the asset URL yourself.
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-react-native 1.16.0 or later. If you use backfill, update the backfill module to 1.16.0 as well.
If a native unit has two or more media items, its creatives contain a file for each media item. properties.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.
  • Media 1 (m1) is the same media as properties.asset and properties.creative. Keep displaying it as before, 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 Type

Displaying Media Items

  • Image: With either useCustomClick setting, a tap inside AdropNativeAdView is an ad click, so a tap on an image you place there is counted like the rest of the ad. 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, taps on the video, including taps on the player’s controls, can also count as ad clicks. 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. Open the requested URL in onOpenWindow and onShouldStartLoadWithRequest.

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.
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.

AdChoices Position

For backfill native ads, you can choose which corner displays the AdChoices badge. Pass preferredAdChoicesPosition as the third argument to the AdropNativeAd constructor.
This setting is a preferred hint for the backfill network and applies only to backfill native ads — direct ads are not affected. The backfill network may override the position depending on its policy.

Next Steps

Banner Ads

Implement banner ads

Interstitial Ads

Implement interstitial ads

Popup Ads

Implement popup ads

Rewarded Ads

Implement rewarded ads