Add iAB Standard Size Experiences to a React Native app

Render Genuin IAB ad slots in a React Native Android app with genuin-react-native-ads-v3 1.4.0.

genuin-react-native-ads-v3 puts a Genuin IAB ad slot (an Interactive Advertising Bureau standard size such as 300×250) on screen as one React component. You pass a tag ID, and the package hosts the native ad view from the iAB Standard Size Experience SDK for Android 0.v3.11, which it pins. The SDK fetches the creative, plays it, tracks impressions and viewability, and reports analytics on its own; there's no player to wire up and no measurement code to add.

The package is Android only. On iOS, <GenuinAd /> renders nothing and takes no space, so a shared screen stays mountable. For the native SDK underneath, see Add iAB Standard Size Experiences to an Android app; for the iOS SDK, see Add iAB Standard Size Experiences to an iOS app.

Requirements

The API key comes from Brand Control Center under Build > Publish Brand Community > SDK Integration, with a Live Environment and a QA Environment key. A tag ID identifies one ad placement. It's the id of an iAB Standard Tag, created in Brand Control Center under Grow > Off Site > Extended > iAB Standard Tag and accepted for your brand. Your Genuin team passes it to you.

Step 1: Install the package

npm install genuin-react-native-ads-v3   # or: yarn add genuin-react-native-ads-v3

Autolinking registers the native module and the BGInstreamAdView view manager. There's nothing to add to MainApplication or MainActivity, and no manifest edit.

Step 2: Configure the Android build

1. Set the toolchain versions in android/build.gradle. React Native libraries read them from rootProject.ext, so your app decides what the module compiles with:

buildscript {
    ext {
        minSdkVersion = 24
        compileSdkVersion = 36
        targetSdkVersion = 36
        kotlinVersion = "2.0.21"
    }
}

1. Enable core-library desugaring and Java 17 in android/app/build.gradle. The React Native 0.83 template already has this block with the same artifact; check before adding it twice:

android {
    compileOptions {
        coreLibraryDesugaringEnabled true
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
}

dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5'
}

Without it the build fails with Invoke-customs are only supported starting with Android O, or the app crashes on the first ad with a java.time class missing. Neither message names Genuin.

1. Keep google() and mavenCentral() in your app's repositories; the React Native template declares both. The Genuin artifacts resolve from Maven Central.
2. Keep the INTERNET permission the template declares. The Genuin libraries don't declare it themselves, and ACCESS_NETWORK_STATE arrives transitively. The SDK's instream-ads module merges in com.google.android.gms.permission.AD_ID to resolve advertising-ID macros in VAST tags; declare advertising-ID use in the Play Console Data safety form, or the submission is rejected.

Step 3: Initialize the SDK

initialize must resolve before any slot mounts. A slot that mounts first throws IllegalStateException: SDK not initialized natively, so gate rendering on state:

import { useEffect, useState } from 'react';
import { Platform } from 'react-native';
import { initialize, setLoggingEnabled } from 'genuin-react-native-ads-v3';

export function useGenuinAds(): boolean {
  const [ready, setReady] = useState(false);
  useEffect(() => {
    if (Platform.OS !== 'android') return;
    if (__DEV__) setLoggingEnabled(true);           // before initialize, to catch start-up lines
    initialize({ apiKey: '<<YOUR_API_KEY>>', env: 'PROD' })
      .then(() => setReady(true))
      .catch(console.error);
  }, []);
  return ready;
}

initialize is safe to call more than once; the SDK builds its graph on the first call only. isInitialized() returns true once it has completed in this process.

setLoggingEnabled(true) turns on the SDK's own diagnostic log, which is off in every published build however your app is built. Read it with adb logcat -s GenuinSDK. The wrapper mirrors each slot's events to a second tag, GenuinAdEvent, in debug builds. Gate logging on __DEV__, because the log names your tag IDs.

To initialize natively instead, before the first React render, call GenuinSDKPluginModule.initSDK(application, "<<YOUR_API_KEY>>") from MainActivity.onCreate. Pass true as a third argument for the QA environment. Both paths land in the same native call.

Step 4: Render an ad slot

import { GenuinAd, GenuinAdFormat, type GenuinAdEvent } from 'genuin-react-native-ads-v3';

export default function ArticleScreen() {
  const ready = useGenuinAds();
  return (
    <>
      <ArticleBody />
      {ready && (
        <GenuinAd
          tagId="{{TAG_ID}}"
          format={GenuinAdFormat.SIZE_300X250}
          onAdEvent={(event: GenuinAdEvent) => console.log(event)}
        />
      )}
    </>
  );
}

tagId is the only required prop. You don't size the slot. The component applies the format's fixed dp size itself, because the native view lays its content out at that size whatever box React Native gives it.

Two slots with the same tag and format need distinct uniqueId values, or they fight over one piece of native state:

<GenuinAd tagId="{{TAG_ID}}" format={GenuinAdFormat.SIZE_320X50} uniqueId="header" />
<GenuinAd tagId="{{TAG_ID}}" format={GenuinAdFormat.SIZE_320X50} uniqueId="footer" />

GENUIN_AD_SIZES exports each format's width, height, and, for the collapsible format, collapsedHeight, so a list can reserve the row height before the slot mounts.

Ad formats

Three formats need layout care:

• SIZE_300X250_COLLAPSIBLE resizes its own box. React Native doesn't re-lay-out a native child that changes size, so the component listens for the collapsed event and switches between height and collapsedHeight. You still receive the event to resize a container around the slot. Setting height in style opts out and pins the box.
• SIZE_1280X720 is declared at its full IAB width, so in a portrait container the box overflows sideways. Give it a landscape or full-screen parent. The native view clamps its own content; the overflow is the React Native box.
• SIZE_FS_LANDSCAPE gets flex: 1 instead of a dp box. In a full-screen parent it needs no style. In a parent that doesn't size its children, such as a ScrollView content container, it renders 0 × 0; give it { width: '100%', aspectRatio: 16 / 9 } or explicit values. The ratio is honoured between 1.25:1 and 2.4:1, and a box outside that band is letter-boxed or pillar-boxed.

Step 5: Supply geo targeting (Optional)

Ad URLs carry geo macros that the ad server expands, such as [DMA_CODE] and [USER_GEO_CITY]. By default the SDK resolves them from the request IP, so most apps need nothing. Supply geo yourself when you know better than the IP, or when you need a DMA code, which the IP lookup can't provide.

import { setGeoLocation } from 'genuin-react-native-ads-v3';

setGeoLocation({
  country: 'US',
  region: 'NY',
  city: 'New York',
  dmaCode: '501',
  latitude: 40.7128,
  longitude: -74.006,
});

Every field is optional and resolves independently, so setting only dmaCode leaves the rest to the IP lookup. setGeoLocation() with no argument clears the value. Setting both latitude and longitude also reports the geo type as device location rather than IP-derived; one coordinate alone is ignored for that purpose.

Timing is forgiving: setGeoLocation doesn't need initialize to have run, and each ad request reads the geo current when it builds its URL. A location that arrives after the first slot is on screen reaches every later request; requests already in flight keep their geo. For one slot that needs a different geo, pass the geoLocation prop; its fields win over the app-wide value, which wins over the IP lookup.

Step 6: Observe lifecycle events

onAdEvent receives a discriminated union with 11 members. Ad positions are 1-based.

<GenuinAd
  tagId="{{TAG_ID}}"
  onAdEvent={(event) => {
    switch (event.type) {
      case 'noAds':
      case 'allAdsCompleted':
        setShowAd(false);                      // reclaim the space yourself
        break;
      case 'started':
        console.log(`ad ${event.index}/${event.total} (${event.adType}) started`);
        break;
    }
  }}
/>

adType reports what the slot led with: 'audio' (a VAST audio ad), 'external' (Pangle or Google Mobile Ads), 'sponsored', 'video', or 'unknown'. It's typed as an open string because the SDK adds labels over time.

Step 7: Enable an external ad network (Optional)

Genuin can fill slots from Pangle (ByteDance) or Google Mobile Ads as well as its own inventory. Both are off by default and need no React Native code: <GenuinAd /> and its events are unchanged, and slots the server books against an external network start filling with adType: 'external'.

1. Turn on the network in android/gradle.properties:

genuinEnablePangle=true
genuinEnableGmaAds=true

1. For Pangle, add ByteDance's repository inside allprojects { repositories { ... } } in android/build.gradle. Pangle isn't on Maven Central, and a POM can't contribute a repository, so the module's own declaration isn't enough:

maven {
    url 'https://artifact.bytedance.com/repository/pangle/'
    content { includeGroupByRegex 'com\\.pangle.*' }
}

If the flag is on and the repository is missing, the build fails at configuration time with a message that names this step.

1. For Google Mobile Ads, declare your application ID in android/app/src/main/AndroidManifest.xml. Google's SDK resolves from the google() repository you already have.

<application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="{{GMA_APPLICATION_ID}}" />
</application>

Before you ship Pangle, three things are yours to handle. Pangle ships native libraries for arm64-v8a and armeabi-v7a only, so on an x86_64 emulator it never fills and looks like a no-fill; test on a device or an arm64 image. Pangle collects device and advertising identifiers and adds the TikTok App Events SDK transitively, so your Play Data safety declaration grows. The module requests personalised ads without a consent signal, so talk to Genuin before shipping Pangle under GDPR or a similar regime.

To confirm a network module is in your APK, turn on logging and look for BGAdNetworkRegistry: ad networks available = [pangle] in logcat. If your app uses Expo prebuild, android/ is generated; put the repository in a config plugin or re-apply it after expo prebuild --clean.

Troubleshooting

Limitations

• Android only: GenuinAd renders nothing on iOS, and the package has no web target.
• Initialize before mounting: a slot mounted before initialize resolves throws natively.
• No pause or resume: playback follows the Android Activity lifecycle, and a JavaScript-only router keeps the Activity resumed, so audio can continue after you navigate away. Unmounting the component stops it.
• Fixed slot sizes: seven formats draw at their IAB dp size; only SIZE_FS_LANDSCAPE adapts, and only between 1.25:1 and 2.4:1.
• Pinned native SDK: the package fixes com.begenuin at 0.v3.11; override with -PgenuinSdkVersion=<version> only on Genuin's advice, because older lines lack events the wrapper references.
• App size: the four required 0.v3.11 artifacts total 6.0 MB of AARs before Media3 and the Google IMA SDK, which are shared if your app already uses them.

See also

• Add iAB Standard Size Experiences to an Android app
• Add iAB Standard Size Experiences to an iOS app
• Integrate the Genuin SDK with React Native apps
• How the Genuin SDK renders ads