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

new AdropNativeAd(unitId: string, useCustomClick?: boolean)
unitId
string
required
Ad unit ID (issued from console)
useCustomClick
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

Methods

MethodDescription
load()Request and load the ad
destroy()Release ad resources

Properties

PropertyTypeDescription
isLoadedbooleanWhether ad is loaded (read-only)
unitIdstringAd unit ID (read-only)
useCustomClickbooleanWhether custom click handling is used (read-only)
creativeIdstringAd creative ID (read-only)
txIdstringTransaction ID (read-only)
campaignIdstringCampaign ID (read-only)
isBackfilledbooleanWhether it’s a backfill ad (read-only)
propertiesAdropNativePropertiesAd properties information (read-only)
listenerAdropNativeAdListenerAd event listener

AdropNativeAdView Component

Container component to display native ads.

Props

interface Props extends ViewProps {
  nativeAd?: AdropNativeAd
}
nativeAd
AdropNativeAd
Native ad instance to display

Usage Example

<AdropNativeAdView nativeAd={nativeAd} style={styles.adContainer}>
  {/* Ad elements */}
</AdropNativeAdView>
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.
<AdropProfileLogoView style={styles.profileLogo} />
Props: ImageProps (React Native Image component properties)

AdropProfileNameView

Text component to display advertiser profile name.
<AdropProfileNameView style={styles.profileName} />
Props: TextProps (React Native Text component properties)

AdropHeadLineView

Text component to display ad title.
<AdropHeadLineView style={styles.headline} />
Props: TextProps (React Native Text component properties)

AdropBodyView

Text component to display ad body text.
<AdropBodyView style={styles.body} />
Props: TextProps (React Native Text component properties)

AdropMediaView

Media component to display ad image or video.
<AdropMediaView style={styles.media} />
Props: ViewProps (React Native View component properties)
For non-backfill ads, video ads should be rendered directly using WebView. (See implementation example)

AdropCallToActionView

Text component to display call-to-action (CTA) message.
<AdropCallToActionView style={styles.cta} />
Props: TextProps (React Native Text component properties)

AdropAdvertiserView

Text component to display advertiser name.
<AdropAdvertiserView style={styles.advertiser} />
Props: TextProps (React Native Text component properties)

AdropIconView

Image component to display ad icon.
<AdropIconView style={styles.icon} />
Props: ImageProps (React Native Image component properties)

AdropNativeAdListener Interface

Listener interface for handling ad events.
interface AdropNativeAdListener {
  onAdReceived?: (ad: AdropNativeAd) => void
  onAdClicked?: (ad: AdropNativeAd) => void
  onAdImpression?: (ad: AdropNativeAd) => void
  onAdFailedToReceive?: (ad: AdropNativeAd, errorCode?: any) => void
}
Callback MethodDescription
onAdReceivedCalled when ad reception is successful
onAdClickedCalled when ad is clicked
onAdImpressionCalled when ad is displayed
onAdFailedToReceiveCalled when ad reception fails

AdropNativeProperties Type

Type containing ad properties information.
type AdropNativeProperties = {
  icon?: string                      // Icon image URL
  cover?: string                     // Cover image URL
  headline?: string                  // Ad title
  body?: string                      // Ad body text
  creative?: string                  // Ad creative HTML (for WebView rendering)
  asset?: string                     // Asset information
  destinationURL?: string            // Destination URL
  advertiserURL?: string             // Advertiser URL
  accountTag?: string                // Account tag
  creativeTag?: string               // Creative tag
  advertiser?: string                // Advertiser name
  callToAction?: string              // Call to action message
  profile?: AdropNativeProfile       // Profile information
  extra?: Record<string, string>     // Additional information
  isBackfilled?: boolean             // Whether it's a backfill ad
}

AdropNativeProfile Type

Type containing advertiser profile information.
type AdropNativeProfile = {
  displayName: string                // Profile display name
  displayLogo: string                // Profile logo image URL
}

Implementation Example

Here’s a complete example of implementing native ads.
import React, { useCallback, useEffect, useMemo, useState } from 'react'
import {
  AdropBodyView,
  AdropHeadLineView,
  AdropMediaView,
  AdropNativeAd,
  AdropNativeAdView,
  AdropProfileLogoView,
  AdropProfileNameView,
} from 'adrop-ads-react-native'
import type { AdropNativeAdListener } from 'adrop-ads-react-native'
import { WebView } from 'react-native-webview'
import {
  Button,
  Dimensions,
  ScrollView,
  StyleSheet,
  Text,
  View,
  Linking,
  Platform,
} from 'react-native'

const NativeAdExample: React.FC = () => {
  const [nativeAd, setNativeAd] = useState<AdropNativeAd>()
  const [isLoaded, setIsLoaded] = useState(false)
  const [errorCode, setErrorCode] = useState('')

  // URL opening handler
  const openUrl = useCallback((url: string) => {
    Linking.openURL(url).catch((err) =>
      console.error('Failed to open URL:', err)
    )
  }, [])

  // Ad event listener
  const listener = useMemo(
    (): AdropNativeAdListener => ({
      onAdReceived: (ad) => {
        console.log('Ad received:', ad.unitId, ad.properties)
        setIsLoaded(true)
        setErrorCode('')
      },
      onAdFailedToReceive: (_, error) => {
        console.log('Ad reception failed:', error)
        setErrorCode(error)
      },
      onAdClicked: (ad) => {
        console.log('Ad clicked:', ad.unitId)
      },
      onAdImpression: (ad) => {
        console.log('Ad impression:', ad.unitId)
      },
    }),
    []
  )

  // Initialize ad
  const initialize = useCallback(
    (unitId: string) => {
      const adropNativeAd = new AdropNativeAd(unitId)
      adropNativeAd.listener = listener

      setNativeAd((prev) => {
        prev?.destroy()
        return adropNativeAd
      })

      setIsLoaded(false)
      setErrorCode('')
    },
    [listener]
  )

  // Initialize ad on component mount
  useEffect(() => {
    initialize('YOUR_UNIT_ID')

    // Release ad on component unmount
    return () => {
      nativeAd?.destroy()
    }
  }, [])

  // Load ad
  const load = () => nativeAd?.load()

  // Render ad view
  const adView = useMemo(() => {
    if (!isLoaded) return null

    return (
      <AdropNativeAdView
        nativeAd={nativeAd}
        style={{
          ...styles.adContainer,
          width: Dimensions.get('window').width,
        }}
      >
        {/* Profile area */}
        <View style={styles.rowContainer}>
          <AdropProfileLogoView style={styles.profileLogo} />
          <AdropProfileNameView style={styles.profileName} />
        </View>

        {/* Ad title */}
        <AdropHeadLineView style={styles.headline} />

        {/* Ad body */}
        <AdropBodyView style={styles.body} />

        {/* Media area */}
        {nativeAd?.isBackfilled ? (
          // Backfill ad: Use AdropMediaView
          <AdropMediaView style={styles.media} />
        ) : (
          // Regular ad: Render with WebView
          <WebView
            source={{
              html: nativeAd?.properties?.creative ?? '',
            }}
            style={styles.media}
            javaScriptEnabled={true}
            mediaPlaybackRequiresUserAction={false}
            allowsInlineMediaPlayback={true}
            scrollEnabled={false}
            onNavigationStateChange={(event) => {
              // Android WebView event
              if (
                event.url &&
                event.url !== 'about:blank' &&
                !event.url.startsWith('data:')
              ) {
                openUrl(event.url)
              }
            }}
            onOpenWindow={(event) => {
              // iOS WebView event (window.open)
              if (event.nativeEvent?.targetUrl) {
                openUrl(event.nativeEvent.targetUrl)
              }
            }}
          />
        )}
      </AdropNativeAdView>
    )
  }, [isLoaded, nativeAd, openUrl])

  return (
    <ScrollView>
      <View style={styles.container}>
        {/* Ad load button */}
        <View style={styles.button}>
          <Button title="Load Ad" onPress={load} />
        </View>

        {/* Ad view */}
        {adView}

        {/* Error display */}
        {errorCode && (
          <Text style={styles.error}>
            Error: {errorCode}
          </Text>
        )}
      </View>
    </ScrollView>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    paddingVertical: 5,
    paddingHorizontal: 16,
  },
  button: {
    marginVertical: 8,
  },
  adContainer: {
    paddingHorizontal: 16,
  },
  rowContainer: {
    flexDirection: 'row',
    justifyContent: 'flex-start',
    alignItems: 'center',
    marginBottom: 8,
  },
  profileLogo: {
    width: 32,
    height: 32,
    marginRight: 8,
    borderRadius: 16,
  },
  profileName: {
    fontSize: 14,
    fontWeight: 'bold',
    color: 'black',
  },
  headline: {
    fontSize: 16,
    fontWeight: 'bold',
    color: 'black',
    marginTop: 8,
  },
  body: {
    fontSize: 14,
    color: 'black',
    marginVertical: 8,
  },
  media: {
    width: '100%',
    height: 360,
    marginTop: 8,
  },
  error: {
    color: 'red',
    marginVertical: 8,
  },
})

export default NativeAdExample

Test Unit IDs

Use the following test unit IDs during development and testing.
PlatformFormatTest Unit ID
Android/iOSNative (Image)PUBLIC_TEST_UNIT_ID_NATIVE
Android/iOSNative Video (16:9)PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_16_9
Android/iOSNative Video (9:16)PUBLIC_TEST_UNIT_ID_NATIVE_VIDEO_9_16
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 CodeDescription
ERROR_CODE_NETWORKNetwork error
ERROR_CODE_INTERNALInternal error
ERROR_CODE_INITIALIZEInitialization error
ERROR_CODE_INVALID_UNITInvalid unit ID
ERROR_CODE_AD_NO_FILLNo ads available
ERROR_CODE_AD_LOADINGAd is loading

Error Handling Example

const listener: AdropNativeAdListener = {
  onAdFailedToReceive: (ad, errorCode) => {
    switch (errorCode) {
      case 'ERROR_CODE_AD_NO_FILL':
        console.log('No ads available - hide ad area')
        break
      case 'ERROR_CODE_NETWORK':
        console.log('Network error - retry')
        setTimeout(() => ad.load(), 3000)
        break
      default:
        console.log('Ad loading failed:', errorCode)
    }
  }
}

Best Practices

1. Resource Cleanup

Always release ad resources when component unmounts.
useEffect(() => {
  const ad = new AdropNativeAd('YOUR_UNIT_ID')
  setNativeAd(ad)

  return () => {
    ad.destroy()
  }
}, [])

2. Backfill Ad Handling

Choose appropriate rendering method based on whether it’s a backfill ad.
{nativeAd?.isBackfilled ? (
  <AdropMediaView style={styles.media} />
) : (
  <WebView source={{ html: nativeAd?.properties?.creative ?? '' }} />
)}

3. URL Handling

Handle URL clicks in WebView to open in external browser.
<WebView
  onNavigationStateChange={(event) => {
    if (event.url && event.url !== 'about:blank') {
      Linking.openURL(event.url)
    }
  }}
/>

4. Selective Use of Ad Elements

Selectively use only the ad elements needed to match your app’s design.
<AdropNativeAdView nativeAd={nativeAd}>
  {/* Minimal configuration: Display only media and title */}
  <AdropHeadLineView style={styles.headline} />
  <AdropMediaView style={styles.media} />
</AdropNativeAdView>

Next Steps