React Native Apex Ad SDK

React Native bridge for the Apex Ad SDK. The package exposes Apex initialization, consent, App Open ads, banners, interstitials, rewarded video, native ads, and Google Wallet pass extension hooks to React Native applications.

Platform Support

Platform	Status
Android	Supported. Uses the native Apex Android SDK artifacts.
iOS	Safe no-op stubs. Methods reject with apex_ios_unavailable until an Apex iOS SDK is available.

Installation

npm install react-native-apex-ad-sdk

For iOS projects, keep CocoaPods in sync:

cd ios && pod install

Android Requirements

• React Native 0.72 or newer
• Android min SDK 21 or newer
• Android compile SDK 35 recommended
• Access to the Apex Android SDK Maven artifacts

The plugin resolves Apex artifacts from mavenLocal() first, then GitHub Packages:

// android/build.gradle
allprojects {
  repositories {
    google()
    mavenCentral()
    mavenLocal()
    maven {
      url = uri("https://maven.pkg.github.com/Madroid2/apex-ad-sdk-android")
      credentials {
        username = System.getenv("GITHUB_ACTOR") ?: "Madroid2"
        password = System.getenv("GITHUB_TOKEN") ?: ""
      }
    }
  }
}

Set the Apex SDK version from the app:

// android/build.gradle
ext {
  apexAdSdkVersion = "1.0.0-SNAPSHOT"
}

For local development against the adjacent Android SDK repo:

cd ../apex-ad-sdk-android
APEX_VERSION=1.0.0-SNAPSHOT ./gradlew publishToMavenLocal

Demo App

This repository includes a runnable React Native demo app in example. It demonstrates initialization, consent, wallet extension installation, banners, MRECT, interstitials, rewarded video, native views, native asset loading, App Open readiness, and event logging.

npm run example:install
npm run example:start
npm run example:android

The demo defaults to debugFakeFill: true, so it can render SDK sample demand without a live ad server. See example/README.md for the full runbook.

Demo Screenshots

The screenshots below were captured from a Pixel emulator running the example app.

Initial state	Banner and MRECT

Native ad	Interstitial

Initialize

Call initialize before mounting ad views or loading full-screen formats.

import ApexAds from 'react-native-apex-ad-sdk';

await ApexAds.initialize({
  appToken: 'YOUR_APP_TOKEN',
  adServerUrl: 'https://your-openrtb-endpoint.com/openrtb/v1/auction',
  trackingUrl: 'https://your-tracking-endpoint.com',
  cacheTtlSeconds: 300,
  gdprConsentString: tcfString,
  usPrivacyString: usPrivacyString,
  debugLogging: __DEV__,
  debugFakeFill: __DEV__,
});

Update consent after initialization when a CMP result changes:

await ApexAds.setConsent({
  gdprApplies: true,
  gdprConsentString: tcfString,
  usPrivacyString: '1YNN',
});

Events

Full-screen and App Open formats emit a single native event stream:

const subscription = ApexAds.addEventListener((event) => {
  switch (event.type) {
    case 'interstitialClosed':
      break;
    case 'rewardEarned':
      break;
    case 'appOpenFailedToLoad':
      console.warn(event.error.message);
      break;
  }
});

subscription.remove();

Banner Ads

ApexBannerAd is a native Android view backed by the Apex MRAID banner renderer.

import { ApexBannerAd } from 'react-native-apex-ad-sdk';

<ApexBannerAd
  placementId="home-banner"
  adSize="BANNER_320x50"
  style={{ width: 320, height: 50 }}
  onAdLoaded={() => console.log('banner loaded')}
  onAdFailed={(event) => console.warn(event.nativeEvent.error.message)}
/>;

Supported sizes:

• BANNER_320x50
• MRECT_300x250
• LEADERBOARD_728x90

Use refreshKey to force a reload without remounting the component:

<ApexBannerAd
  placementId="feed-mrect"
  adSize="MRECT_300x250"
  refreshKey={String(refreshCount)}
  style={{ width: 300, height: 250 }}
/>

Interstitial Ads

const interstitial = await ApexAds.loadInterstitial('level-complete');

if (await ApexAds.isInterstitialReady(interstitial.adKey)) {
  await ApexAds.showInterstitial(interstitial.adKey);
}

To manage a stable placement key yourself:

await ApexAds.loadInterstitial('level-complete', {
  adKey: 'level-complete-interstitial',
});

Interstitial instances are destroyed automatically after close. You can also destroy explicitly:

await ApexAds.destroyInterstitial('level-complete-interstitial');

Rewarded Video

const rewarded = await ApexAds.loadRewardedVideo('rewarded-coins');
await ApexAds.showRewardedVideo(rewarded.adKey);

Reward delivery should be driven by the rewardEarned event:

const subscription = ApexAds.addEventListener((event) => {
  if (event.type === 'rewardEarned' && event.placementId === 'rewarded-coins') {
    grantCoins();
  }
});

Native Ads

For the easiest trackable implementation, mount ApexNativeAdView. It loads, renders a default native template, fires impression tracking, and opens the SDK click handler from the native view.

import { ApexNativeAdView } from 'react-native-apex-ad-sdk';

<ApexNativeAdView
  placementId="feed-native"
  style={{ width: '100%', minHeight: 280 }}
  onAdLoaded={(event) => {
    console.log(event.nativeEvent.assets.title);
  }}
  onAdFailed={(event) => {
    console.warn(event.nativeEvent.error.message);
  }}
/>;

For custom JS layouts, load native assets directly:

const native = await ApexAds.loadNativeAd('feed-native');

console.log(native.assets.title);
console.log(native.assets.imageUrl);

await ApexAds.destroyNativeAd(native.adKey);

When using custom JS layouts, pair the rendered ad with a native view integration before production so click and impression tracking remain SDK-owned.

App Open Ads

Initialize App Open once after the SDK is initialized:

await ApexAds.initializeAppOpen('app-open', {
  enabled: true,
  frequencyCapHours: 1,
  adExpiryMinutes: 30,
});

The Apex Android SDK handles foreground detection, preloading, expiry, and frequency caps.

const ready = await ApexAds.isAppOpenAdReady();
await ApexAds.setAppOpenEnabled(ready);

Google Wallet Pass Ads

Wallet pass ads are enabled by installing the Apex wallet extension after SDK initialization:

await ApexAds.initialize({ appToken: 'YOUR_APP_TOKEN' });
await ApexAds.installWalletExtension();

The extension activates wallet CTAs in eligible interstitial and MRECT banner responses. Wallet lifecycle events are available on banners through view callbacks and on interstitials through the shared event stream.

API Reference

Default Export

ApexAds.initialize(config)
ApexAds.isInitialized()
ApexAds.setConsent(consent)
ApexAds.installWalletExtension()
ApexAds.addEventListener(listener)
ApexAds.loadInterstitial(placementId, options?)
ApexAds.showInterstitial(adKey)
ApexAds.isInterstitialReady(adKey)
ApexAds.destroyInterstitial(adKey)
ApexAds.loadRewardedVideo(placementId, options?)
ApexAds.showRewardedVideo(adKey)
ApexAds.isRewardedVideoReady(adKey)
ApexAds.destroyRewardedVideo(adKey)
ApexAds.loadNativeAd(placementId, options?)
ApexAds.destroyNativeAd(adKey)
ApexAds.initializeAppOpen(placementId, options?)
ApexAds.setAppOpenEnabled(enabled)
ApexAds.setAppOpenFrequencyCapHours(hours)
ApexAds.setAppOpenAdExpiryMinutes(minutes)
ApexAds.isAppOpenAdReady()
ApexAds.destroyAppOpen()

Components

ApexBannerAd
ApexNativeAdView

Troubleshooting

Apex artifacts cannot be resolved

Publish the Android SDK to Maven Local or configure GitHub Packages credentials. For GitHub Packages, the token must have permission to read Madroid2/apex-ad-sdk-android.

ApexAds.initialize() rejects on Android

Confirm appToken is non-empty and initialization runs before any ad view mounts or ad load method is called.

Banner has no visible size

React Native views need explicit dimensions. Set style={{ width: 320, height: 50 }} for BANNER_320x50, style={{ width: 300, height: 250 }} for MRECT_300x250, or equivalent responsive constraints.

iOS methods reject

This package currently ships iOS stubs only. Guard ad calls by platform when building a cross-platform app:

if (Platform.OS === 'android') {
  await ApexAds.initialize({ appToken: 'YOUR_APP_TOKEN' });
}