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)
  variant: 'A',               // Optional: A/B test variant
  ext: 'cat=sports',          // Optional, iOS only: AppView ext parameter
});

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.
variant	string	undefined	Optional A/B test variant string. To change it later, see Screen Variant and Ext.
ext	string	undefined	iOS only. Optional AppView ext parameter to start with. The SDK percent-encodes it, so pass it unencoded.

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 — see Automatic Ad Queueing for when you do and don't need it.

---

Automatic Ad Queueing

• Banner and App Open ads queue automatically if requested before the SDK finishes initializing — call them any time (e.g. right after init()); they load once the SDK is ready.
• Interstitial and Rewarded ads are best loaded after the SDK is ready, for reliable delivery. Wait for the SDK_READY event:

import {
  init,
  loadInterstitialAd,
  loadRewardedAd,
  loadAppOpenAd,
  addEventListener,
  EmpowerAdsEvents,
} from '@empower-nokta/react-native-mobile-ads';

// Initialize
init({ appAdIdentifier: 'your_app_identifier' });

// Banner + App Open queue automatically — safe to call now
loadAppOpenAd('app_open_zone_id');

// Load interstitial / rewarded once the SDK is ready
const unsub = addEventListener(EmpowerAdsEvents.SDK_READY, () => {
  loadInterstitialAd('interstitial_zone_id');
  loadRewardedAd('rewarded_zone_id');
  unsub(); // fires 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:

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

import { init } from '@empower-nokta/react-native-mobile-ads';

init({
  appAdIdentifier: 'your_app_identifier',
  privacyMode: 'automatic',    // This is the default — you can omit it
});

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).

Note (iOS): In automatic mode the SDK starts its ad networks once the user has answered the ATT prompt, so ads load after that answer. Ads requested before it are queued, not lost.

---

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);

---

Screen Variant and Ext (iOS)

The AppView variant and ext decide which ads the backend serves. You can change them at runtime — for example, to serve different ads on each screen.

import { setScreenInfo, setVariant, setExt } from '@empower-nokta/react-native-mobile-ads';

// When a screen opens: set both with one AppView request
const applied = await setScreenInfo('@market-popular', 'cat=sports&rec=a,b');
if (applied) {
  // The new ads are ready — load zones that are new to this screen now
}

// Or change one of them
await setVariant('@market-popular');
await setExt('cat=sports');

Function	Returns	Description
setScreenInfo(variant, ext)	Promise<boolean>	Sets the variant and ext together, so the screen costs one AppView request. Commas in ext are encoded too, so a value can carry its own commas.
setVariant(variant)	Promise<boolean>	Sets the variant. Pass '' to clear it.
setExt(ext)	Promise<boolean>	Sets the ext. Commas stay separators. Pass '' to clear it.

Each promise resolves:

• true once the new ads are ready. Banners on screen update by themselves.
• false when the value was only stored — called before init, in which case it is sent with init — or when no response arrived within 15 seconds.

Notes:

• A call with the values already in use resolves true at once, without a request. Calls within 150 ms of each other share one request.
• The SDK percent-encodes ext. Pass it unencoded, or it is encoded twice.
• On Android these functions resolve false and do nothing.

---

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' });