React Native SDK

The Adzen React Native SDK embeds contextual ads inside user-generated content feeds on iOS and Android. It handles API calls, MRC-compliant viewability tracking, and pixel firing automatically.

Installation

npm install @adzen/react-native

Minimum React Native version: 0.72. Supports New Architecture (Fabric).

Quick Start

Initialize the SDK

Call AdzenProvider once at the root of your app. Use the sandbox API key during development.

App.tsx

import { AdzenProvider } from '@adzen/react-native'
 
export default function App() {
  return (
    <AdzenProvider
      apiKey={process.env.ADZEN_API_KEY!}
      environment="sandbox"   // 'sandbox' | 'production'
    >
      <MainNavigator />
    </AdzenProvider>
  )
}

Render an ad alongside a post

Drop an <AdzenAd /> component anywhere you want a contextual ad to appear. The component handles matching, rendering, viewability tracking, and dismissal.

PostFeed.tsx

import { AdzenAd } from '@adzen/react-native'
 
function PostFeed({ posts }) {
  return (
    <FlatList
      data={posts}
      renderItem={({ item, index }) => (
        <>
          <PostCard post={item} />
          {/* Show an ad after every 3rd post */}
          {(index + 1) % 3 === 0 && (
            <AdzenAd
              postId={item.id}
              message={item.body}
              onDismiss={() => console.log('ad dismissed')}
            />
          )}
        </>
      )}
    />
  )
}

(Optional) Hook API directly

If you want to render the ad yourself instead of using <AdzenAd />, use the useAdzenMatch hook to fetch a match and the imperative trackImpression helper to report viewability.

import { useAdzenMatch, trackImpression } from '@adzen/react-native'
 
function MyAdSlot({ postId, message }) {
  const { ad, loading, error } = useAdzenMatch({ postId, message })
 
  if (!ad) return null
 
  return (
    <Pressable
      onPress={() => Linking.openURL(ad.click_through_url)}
      onLayout={() => trackImpression(postId, ad.ad_id)}
    >
      <Text>{ad.title}</Text>
      <Text>{ad.cta}</Text>
    </Pressable>
  )
}

API Reference

`<AdzenProvider>`

Wrap your app once. Provides context to all <AdzenAd> components and hooks.

Prop	Type	Required	Description
`apiKey`	`string`	Yes	Your subscription key
`environment`	`'sandbox' \| 'production'`	No	Defaults to `'production'`
`timeout`	`number`	No	Request timeout in ms (default: `5000`)
`onError`	`(error: AdzenError) => void`	No	Global error handler

`<AdzenAd>`

Renders a matched ad with default styling. Accepts all View style props.

Prop	Type	Required	Description
`postId`	`string`	Yes	Unique identifier for the post
`message`	`string`	Yes	Post text to match against
`onDismiss`	`() => void`	No	Called when user dismisses the ad
`onClick`	`(adId: string) => void`	No	Called when user taps the CTA
`renderAd`	`(ad: Ad) => ReactNode`	No	Custom renderer (overrides default UI)

`useAdzenMatch(options)`

Hook that returns a matched ad for a given post.

const { ad, loading, error, refetch } = useAdzenMatch({
  postId: string,
  message: string,
  location?: string,   // e.g. 'US-CA' — overrides IP-based geo
  enabled?: boolean,   // set false to defer fetching
})

`trackImpression(postId, adId)`

Records a viewable impression. Call this when the ad is ≥50% visible on screen for ≥1 second.

`dismissAd(postId, adId)`

Suppresses the ad in this thread. Call this when the user dismisses the ad.

Troubleshooting

Ad doesn't render — check that postId is unique per post and message is non-empty. Check the developer console for [adzen] log lines.

Impressions not counting — the SDK uses React Native's onLayout and onViewableItemsChanged (for FlatList). Ensure the component is actually on screen — conditionally-rendered or off-screen components don't fire impressions.

401 errors — verify your apiKey matches the environment. Sandbox keys don't work in production and vice versa.

JavaScript iOS (Swift)