Configuration

This guide explains how to initialize and configure the Empower Mobile Ads SDK in your React Native application.

SDK Initialization

Initialize the SDK as early as possible in your application lifecycle — ideally in your root App component.

Basic Initialization

import { useEffect } from 'react';
import { Platform } from 'react-native';
import { init } from '@empower-nokta/react-native-mobile-ads';
export default function App() {
  useEffect(() => {
    const appId = Platform.select({
      android: 'your_android_app_identifier',
      ios: 'your_ios_app_identifier',
    });
    init({ appAdIdentifier: appId });
  }, []);
  return (
    // Your app content
  );
}

Important: Replace the identifiers with the app identifiers provided by Empower.

Initialization with Options

import { init } from '@empower-nokta/react-native-mobile-ads';
init({
  appAdIdentifier: 'your_app_identifier',
  debugMode: false,           // Enable debug logging (disable in production)
  logLevel: 'default',        // Log verbosity level
  privacyMode: 'automatic',   // GDPR consent mode (see GDPR Compliance section)
  consentFormDelay: 1.5,      // iOS only: delay before consent form (seconds)
  variant: 'A',               // Optional: A/B test variant
});

Configuration Options

Option	Type	Default	Description
`appAdIdentifier`	`string`	—	Required. Your app identifier from Empower.
`debugMode`	`boolean`	`false`	Enables verbose logging and test ads. Disable in production.
`logLevel`	`string`	`'none'`	Controls the verbosity of SDK logs.
`privacyMode`	`string`	`'automatic'`	GDPR consent mode: `'automatic'`, `'nonPersonalized'`, or `'manual'`. See GDPR Compliance section.
`consentFormDelay`	`number`	`1.5`	iOS only. Delay in seconds before showing the UMP consent form.
`variant`	`string`	`undefined`	Optional A/B test variant string.

Log Levels

Level	Description
`'all'`	Logs all messages including debug information
`'default'`	Logs general information and errors
`'warning'`	Logs warnings and errors only
`'error'`	Logs errors only
`'none'`	Disables all logging

Listening for SDK Ready State (Optional)

If you need to know exactly when the SDK is ready (for analytics, UI updates, etc.), use the event listener:

import { addEventListener, EmpowerAdsEvents } from '@empower-nokta/react-native-mobile-ads';
const unsubscribe = addEventListener(EmpowerAdsEvents.SDK_READY, () => {
  console.log('Empower SDK is ready');
});
const unsubscribeFailed = addEventListener(EmpowerAdsEvents.SDK_FAILED, (error) => {
  console.log('Empower SDK initialization failed', error);
});
// Clean up when no longer needed
unsubscribe();
unsubscribeFailed();

Note: This listener is optional. Since all ad types automatically queue, you don't need to wait for SDK ready before loading ads.

Automatic Ad Queueing

Banner and app open ads automatically queue if called before SDK initialization completes. However, interstitial and rewarded ads should be loaded after the SDK is fully initialized to ensure reliable delivery.

A practical approach is to listen for the first banner status event (which signals that the SDK has finished parsing ad zones) before loading interstitials or rewarded ads:

import {
  init,
  loadInterstitialAd,
  loadAppOpenAd,
  addEventListener,
  EmpowerAdsEvents,
} from '@empower-nokta/react-native-mobile-ads';
// Initialize
init({ appAdIdentifier: 'your_app_identifier' });
// App open ads queue automatically
loadAppOpenAd('app_open_zone_id');
// Load interstitial after SDK is ready (banner status is a reliable signal)
const unsub = addEventListener(EmpowerAdsEvents.BANNER_STATUS, () => {
  loadInterstitialAd('interstitial_zone_id');
  unsub(); // Only need to trigger once
});

GDPR Compliance

The SDK supports three privacy modes for GDPR consent management. Choose the mode that fits your app's requirements.

Privacy Modes

Mode	Description
`'automatic'`	Recommended. SDK automatically handles UMP consent form + ATT permission (iOS 14+). Serves personalized ads when consent is granted.
`'nonPersonalized'`	SDK manages consent automatically but always requests non-personalized ads, regardless of user consent.
`'manual'`	SDK does not show any consent UI. You are responsible for calling `requestConsent()` and `showPrivacyOptionsForm()` yourself.

Automatic Mode (Default)

In automatic mode, the SDK handles the entire consent flow:

Android: Shows the Google UMP consent form if the user is in a GDPR region.
iOS: Shows the UMP consent form first, then requests ATT permission (iOS 14+) after a configurable delay.

import { init } from '@empower-nokta/react-native-mobile-ads';
init({
  appAdIdentifier: 'your_app_identifier',
  privacyMode: 'automatic',    // This is the default — you can omit it
  consentFormDelay: 1.5,        // iOS: seconds to wait before showing UMP form
});

No additional code is required. The SDK detects the user's region and only shows the consent form when legally required (e.g., EEA/UK for GDPR).

Tip: Set consentFormDelay to match your splash screen duration so the consent form doesn't appear too early.

Manual Mode

In manual mode, the SDK does not show any consent UI automatically. Use this when you want full control over when and how consent is collected — for example, if you have a custom onboarding flow.

import {
  init,
  requestConsent,
  isPrivacyOptionsRequired,
  showPrivacyOptionsForm,
} from '@empower-nokta/react-native-mobile-ads';
// Step 1: Initialize with manual mode
init({
  appAdIdentifier: 'your_app_identifier',
  privacyMode: 'manual',
});
// Step 2: Request consent at the right moment (e.g., after onboarding)
await requestConsent();
// Step 3: Show a "Manage Privacy" button if required
const showButton = await isPrivacyOptionsRequired();
if (showButton) {
  // Render a button in your settings screen that calls:
  // showPrivacyOptionsForm();
}

Manual Mode API

Function	Returns	Description
`requestConsent()`	`Promise<boolean>`	Shows the Google UMP consent form. On Android, auto-detects GDPR region. On iOS, shows UMP form via `EMAPrivacyManager`.
`isPrivacyOptionsRequired()`	`Promise<boolean>`	Returns `true` if a "Manage Privacy" button should be shown (GDPR requirement). Call after `requestConsent()`.
`showPrivacyOptionsForm()`	`Promise<boolean>`	Shows the privacy options form so the user can change their consent. Use this for a "Manage Privacy" button in your settings.

Non-Personalized Mode

Use this mode if you want to serve only non-personalized ads regardless of user consent status:

init({
  appAdIdentifier: 'your_app_identifier',
  privacyMode: 'nonPersonalized',
});

The SDK still manages consent forms automatically (same as 'automatic'), but all ad requests are flagged as non-personalized.

Note: You can also toggle non-personalized ads at runtime using setNonPersonalizedAds(true), regardless of the privacy mode.

Runtime Configuration

You can change SDK settings at runtime using these functions:

import {
  setDebugMode,
  setLogLevel,
  setNonPersonalizedAds,
  setAdsDisabled,
} from '@empower-nokta/react-native-mobile-ads';
// Enable/disable debug mode
setDebugMode(false);
// Change log level
setLogLevel('error');
// Toggle non-personalized ads
setNonPersonalizedAds(true);
// Disable all ads (e.g., for premium users)
setAdsDisabled(true);

Checking SDK Status

import { isSdkInitialized } from '@empower-nokta/react-native-mobile-ads';
const isReady = await isSdkInitialized();
if (isReady) {
  // Safe to load ads
}

Disabling Ads for Premium Users

import { setAdsDisabled } from '@empower-nokta/react-native-mobile-ads';
// Disable all ads for premium users
function userPurchasedPremium() {
  setAdsDisabled(true);
}
// Re-enable ads if subscription expires
function premiumSubscriptionExpired() {
  setAdsDisabled(false);
}

Shutdown

Use shutdown() when you no longer want to show ads:

import { init, shutdown } from '@empower-nokta/react-native-mobile-ads';
// Stop all ads and release resources
shutdown();
// Reinitialize when you want to show ads again
init({ appAdIdentifier: 'your_app_identifier' });

#SDK Initialization

#Basic Initialization

#Initialization with Options

#Configuration Options

#Log Levels

#Listening for SDK Ready State (Optional)

#Automatic Ad Queueing

#GDPR Compliance

#Privacy Modes

#Automatic Mode (Default)

#Manual Mode

#Manual Mode API

#Non-Personalized Mode

#Runtime Configuration

#Checking SDK Status

#Disabling Ads for Premium Users

#Shutdown