NativeAd

Displays a contextually targeted native ad inline within your app's feed or UI. The component auto-sizes to the creative height and collapses to zero when no ad is available.

Basic Usage

import { NativeAd } from '@simula/ads-react-native';

function CharacterFeed({ characters }) {
  return characters.map((character, index) => (
    <>
      <CharacterCard key={character.id} {...character} />
      {index % 10 === 9 && (
        <NativeAd
          adUnitId="SIM-NAT-XXXXXXXX"
          position={index}
          onImpression={(data) => {
            console.log('Impression:', data.impressionId);
          }}
        />
      )}
    </>
  ));
}

Props

Prop	Type	Default	Description
adUnitId	string	—	Ad unit ID from the publisher dashboard. Used for measurement and improved targeting
position	number	0	Index of this slot within the feed. Sent to the backend for reporting and session-based logic — set it to the item's index whenever ads are interspersed in a list
theme	"dark" | "light" | "system"	—	Color theme for the ad card. "system" follows the device setting
preloadedAdId	string	—	ID from SimulaAds.preloadNativeAd() to render a cached ad instantly
metadata	Record<string, string>	—	Up to 10 key/value labels for reporting. See Metadata
width	number | string	fills parent	Width in dp, or a string with % or px suffix (e.g. "80%", "320px"). Minimum 300px. Height is auto-managed
onImpression	(data: NativeAdData) => void	—	Fires when the ad is >=50% visible for >=1 second
onClick	() => void	—	Fires when the user taps the ad CTA
onPaid	(adValue: AdValue) => void	—	Estimated per-impression revenue, co-timed with onImpression. See AdValue
onError	(error: NativeAdError) => void	—	Fires on load or render failure

Metadata

Attach up to 10 key/value labels to segment your reporting:

<NativeAd
  adUnitId="SIM-NAT-XXXXXXXX"
  position={index}
  metadata={{ screen: 'search', tab: 'for_you' }}
/>

Keys: ≤64 chars, no $ prefix, no .. Values: ≤256 chars. Extra or invalid entries are dropped.

Preloading

Preload ads before they scroll into view for instant rendering:

import { SimulaAds } from '@simula/ads-react-native';

const preloadedId = await SimulaAds.preloadNativeAd({
  adUnitId: 'SIM-NAT-XXXXXXXX',
  position: 8,
  theme: 'system',
});

// Later, render with the cached ad. Pass the same `position` you preloaded
// with, since it's the slot's actual index in the feed.
<NativeAd
  adUnitId="SIM-NAT-XXXXXXXX"
  position={8}
  preloadedAdId={preloadedId ?? undefined}
/>

// Clean up if the ad was never displayed
SimulaAds.destroyPreloadedAd(preloadedId);

Set the metadata prop on <NativeAd>, not the preload call. See Metadata.

Invalidation

Force-refresh a specific slot or clear all cached native ads:

SimulaAds.invalidateNativeAd({ adUnitId: 'SIM-NAT-XXXXXXXX' });
SimulaAds.invalidateNativeAds();