@ezoic/react-native-sdk 1.0.0 → 1.2.0

package/src/EzoicInterstitialAd.ts

@@ -0,0 +1,126 @@
+import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
+import NativeEzoicAds from './NativeEzoicAds';
+import { coerceAdUnitId } from './helpers';
+
+/** Lifecycle callbacks for an interstitial ad. All are optional. */
+export interface EzoicInterstitialAdListeners {
+  onShown?: () => void;
+  onFailedToShow?: (error: { message: string; code?: number }) => void;
+  onImpression?: () => void;
+  onClicked?: () => void;
+  onDismissed?: () => void;
+}
+
+/** The single native event name carrying every interstitial lifecycle signal. */
+const INTERSTITIAL_EVENT = 'EzoicInterstitialAdEvent';
+
+interface InterstitialNativeEvent {
+  adUnitIdentifier: string;
+  type: 'shown' | 'failedToShow' | 'impression' | 'clicked' | 'dismissed';
+  message?: string;
+  code?: number;
+}
+
+// A single shared emitter is sufficient — events are routed to the right
+// instance by adUnitIdentifier below.
+const emitter = new NativeEventEmitter(NativeEzoicAds as never);
+
+/**
+ * An interstitial ad. Use the static `load` to fetch an ad ahead of time, then
+ * call `show()` to present it full-screen at a natural transition point.
+ * Interstitials carry no reward.
+ *
+ * ```ts
+ * const ad = await EzoicInterstitialAd.load('12345');
+ * ad.setListeners({ onDismissed: () => console.log('closed') });
+ * await ad.show();
+ * ```
+ *
+ * Mirrors the native `EzoicInterstitialAd` load/show lifecycle on both
+ * platforms. Interstitial ads are single-use — load a new one for the next
+ * opportunity.
+ */
+export class EzoicInterstitialAd {
+  /** The Ezoic ad unit identifier this ad was loaded for. */
+  readonly adUnitIdentifier: string;
+
+  private listeners: EzoicInterstitialAdListeners = {};
+  private subscription: EmitterSubscription | null = null;
+
+  private constructor(adUnitIdentifier: string) {
+    this.adUnitIdentifier = adUnitIdentifier;
+    this.subscription = emitter.addListener(
+      INTERSTITIAL_EVENT,
+      (raw: unknown) => {
+        const event = raw as InterstitialNativeEvent;
+        if (event.adUnitIdentifier !== this.adUnitIdentifier) return;
+        this.handleEvent(event);
+      }
+    );
+  }
+
+  /**
+   * Loads an interstitial ad for the given Ezoic ad unit identifier. Resolves
+   * with a ready-to-show `EzoicInterstitialAd`, or rejects if no ad could be
+   * loaded.
+   */
+  static async load(adUnitIdentifier: string): Promise<EzoicInterstitialAd> {
+    const id = coerceAdUnitId(adUnitIdentifier);
+    const ad = new EzoicInterstitialAd(id);
+    try {
+      await NativeEzoicAds.loadInterstitialAd(id);
+      return ad;
+    } catch (error) {
+      ad.destroy();
+      throw error;
+    }
+  }
+
+  /** Registers lifecycle callbacks. Replaces any previously set listeners. */
+  setListeners(listeners: EzoicInterstitialAdListeners): void {
+    this.listeners = listeners;
+  }
+
+  /**
+   * Presents the interstitial ad full-screen. Resolves when the ad is
+   * dismissed. Rejects if the ad was not ready (load first) or failed to
+   * present.
+   */
+  async show(): Promise<void> {
+    await NativeEzoicAds.showInterstitialAd(this.adUnitIdentifier);
+  }
+
+  /** Releases the event subscription. Safe to call multiple times. */
+  destroy(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+    this.listeners = {};
+  }
+
+  private handleEvent(event: InterstitialNativeEvent): void {
+    switch (event.type) {
+      case 'shown':
+        this.listeners.onShown?.();
+        break;
+      case 'failedToShow':
+        this.listeners.onFailedToShow?.({
+          message: event.message ?? '',
+          code: event.code,
+        });
+        // Failure to show is terminal — the native ad is single-use.
+        this.destroy();
+        break;
+      case 'impression':
+        this.listeners.onImpression?.();
+        break;
+      case 'clicked':
+        this.listeners.onClicked?.();
+        break;
+      case 'dismissed':
+        this.listeners.onDismissed?.();
+        // Dismissal is terminal — the native ad is single-use.
+        this.destroy();
+        break;
+    }
+  }
+}

package/src/EzoicRewardedAd.ts

@@ -0,0 +1,143 @@
+import { NativeEventEmitter, type EmitterSubscription } from 'react-native';
+import NativeEzoicAds from './NativeEzoicAds';
+import { coerceAdUnitId, mapRewardResult } from './helpers';
+
+/** A reward earned by the user for completing a rewarded ad. */
+export interface EzoicReward {
+  type: string;
+  amount: number;
+}
+
+/** Lifecycle callbacks for a rewarded ad. All are optional. */
+export interface EzoicRewardedAdListeners {
+  onShown?: () => void;
+  onFailedToShow?: (error: { message: string; code?: number }) => void;
+  onImpression?: () => void;
+  onClicked?: () => void;
+  onDismissed?: () => void;
+  onUserEarnedReward?: (reward: EzoicReward) => void;
+}
+
+/** The single native event name carrying every rewarded lifecycle signal. */
+const REWARDED_EVENT = 'EzoicRewardedAdEvent';
+
+interface RewardedNativeEvent {
+  adUnitIdentifier: string;
+  type:
+    | 'shown'
+    | 'failedToShow'
+    | 'impression'
+    | 'clicked'
+    | 'dismissed'
+    | 'reward';
+  message?: string;
+  code?: number;
+  rewardType?: string;
+  rewardAmount?: number;
+}
+
+// A single shared emitter is sufficient — events are routed to the right
+// instance by adUnitIdentifier below.
+const emitter = new NativeEventEmitter(NativeEzoicAds as never);
+
+/**
+ * A rewarded ad. Use the static `load` to fetch an ad ahead of time, then call
+ * `show()` to present it and grant the reward when the user finishes watching.
+ *
+ * ```ts
+ * const ad = await EzoicRewardedAd.load('12345');
+ * ad.setListeners({ onDismissed: () => console.log('closed') });
+ * const reward = await ad.show();
+ * if (reward) grantReward(reward.amount);
+ * ```
+ *
+ * Mirrors the native `EzoicRewardedAd` load/show lifecycle on both platforms.
+ * Rewarded ads are single-use — load a new one for the next opportunity.
+ */
+export class EzoicRewardedAd {
+  /** The Ezoic ad unit identifier this ad was loaded for. */
+  readonly adUnitIdentifier: string;
+
+  private listeners: EzoicRewardedAdListeners = {};
+  private subscription: EmitterSubscription | null = null;
+
+  private constructor(adUnitIdentifier: string) {
+    this.adUnitIdentifier = adUnitIdentifier;
+    this.subscription = emitter.addListener(REWARDED_EVENT, (raw: unknown) => {
+      const event = raw as RewardedNativeEvent;
+      if (event.adUnitIdentifier !== this.adUnitIdentifier) return;
+      this.handleEvent(event);
+    });
+  }
+
+  /**
+   * Loads a rewarded ad for the given Ezoic ad unit identifier. Resolves with
+   * a ready-to-show `EzoicRewardedAd`, or rejects if no ad could be loaded.
+   */
+  static async load(adUnitIdentifier: string): Promise<EzoicRewardedAd> {
+    const id = coerceAdUnitId(adUnitIdentifier);
+    const ad = new EzoicRewardedAd(id);
+    try {
+      await NativeEzoicAds.loadRewardedAd(id);
+      return ad;
+    } catch (error) {
+      ad.destroy();
+      throw error;
+    }
+  }
+
+  /** Registers lifecycle callbacks. Replaces any previously set listeners. */
+  setListeners(listeners: EzoicRewardedAdListeners): void {
+    this.listeners = listeners;
+  }
+
+  /**
+   * Presents the rewarded ad full-screen. Resolves with the earned reward, or
+   * `null` if the ad was dismissed before the reward was earned. Rejects if the
+   * ad was not ready (load first) or failed to present.
+   */
+  async show(): Promise<EzoicReward | null> {
+    const result = await NativeEzoicAds.showRewardedAd(this.adUnitIdentifier);
+    return mapRewardResult(result);
+  }
+
+  /** Releases the event subscription. Safe to call multiple times. */
+  destroy(): void {
+    this.subscription?.remove();
+    this.subscription = null;
+    this.listeners = {};
+  }
+
+  private handleEvent(event: RewardedNativeEvent): void {
+    switch (event.type) {
+      case 'shown':
+        this.listeners.onShown?.();
+        break;
+      case 'failedToShow':
+        this.listeners.onFailedToShow?.({
+          message: event.message ?? '',
+          code: event.code,
+        });
+        // Failure to show is terminal — the native ad is single-use.
+        this.destroy();
+        break;
+      case 'impression':
+        this.listeners.onImpression?.();
+        break;
+      case 'clicked':
+        this.listeners.onClicked?.();
+        break;
+      case 'reward':
+        this.listeners.onUserEarnedReward?.({
+          type: event.rewardType ?? '',
+          amount: event.rewardAmount ?? 0,
+        });
+        break;
+      case 'dismissed':
+        this.listeners.onDismissed?.();
+        // Dismissal is terminal — the native ad is single-use.
+        this.destroy();
+        break;
+    }
+  }
+}

package/src/NativeEzoicAds.ts

@@ -10,12 +10,31 @@ export interface EzoicConfig {
   testMode?: boolean;
 }
 
+/**
+ * Result of `showRewardedAd`. `earned` is true when the user completed the ad
+ * and earned the reward; `type`/`amount` describe the granted reward (empty/0
+ * when the ad was dismissed without earning). The public `EzoicRewardedAd.show`
+ * maps this to `EzoicReward | null`.
+ */
+export interface EzoicRewardResult {
+  earned: boolean;
+  type: string;
+  amount: number;
+}
+
 export interface Spec extends TurboModule {
   initialize(config: EzoicConfig): Promise<void>;
   setGDPRConsent(applies: boolean, consentString?: string): void;
   setGPPConsent(gppString?: string, sectionIds?: string): void;
   setSubjectToCOPPA(value: boolean): void;
   trackPageview(): Promise<boolean>;
+  loadRewardedAd(adUnitIdentifier: string): Promise<void>;
+  showRewardedAd(adUnitIdentifier: string): Promise<EzoicRewardResult>;
+  loadInterstitialAd(adUnitIdentifier: string): Promise<void>;
+  showInterstitialAd(adUnitIdentifier: string): Promise<void>;
+  // Required by NativeEventEmitter for the ad lifecycle events.
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>('EzoicReactNativeSdk');

package/src/helpers.ts

@@ -28,3 +28,22 @@ export function normalizeSize(size: string | undefined): string {
 export function coerceAdUnitId(adUnitIdentifier: string): string {
   return String(adUnitIdentifier);
 }
+
+export interface RewardResultLike {
+  earned: boolean;
+  type: string;
+  amount: number;
+}
+
+/**
+ * Maps the native `showRewardedAd` result to the public reward shape: the
+ * `{ type, amount }` reward when earned, otherwise `null` (dismissed unearned).
+ */
+export function mapRewardResult(
+  result: RewardResultLike | null | undefined
+): { type: string; amount: number } | null {
+  if (result && result.earned) {
+    return { type: result.type, amount: result.amount };
+  }
+  return null;
+}

package/src/index.tsx

@@ -4,6 +4,15 @@ import EzoicBannerNative from './EzoicBannerViewNativeComponent';
 import { coerceAdUnitId, normalizeConfig, normalizeSize } from './helpers';
 
 export type { EzoicConfig };
+export {
+  EzoicRewardedAd,
+  type EzoicReward,
+  type EzoicRewardedAdListeners,
+} from './EzoicRewardedAd';
+export {
+  EzoicInterstitialAd,
+  type EzoicInterstitialAdListeners,
+} from './EzoicInterstitialAd';
 
 export const EzoicAds = {
   initialize(config: EzoicConfig): Promise<void> {