@ezoic/react-native-sdk 1.11.0 → 1.13.0

package/src/EzoicConsent.ts

@@ -0,0 +1,69 @@
+/** Which button the user closed the consent dialog with. */
+export type EzoicConsentDecision = 'acceptAll' | 'rejectAll' | 'custom';
+
+/**
+ * Result of `EzoicAds.presentConsentIfRequired` / `presentConsentSettings`.
+ *
+ * - `notRequired`: GDPR doesn't apply, the built-in CMP is disabled, another
+ *   CMP owns consent, or consent is managed by the app (`setGDPRConsent`, or
+ *   `autoReadConsent: false`).
+ * - `alreadyDecided`: a still-valid decision is stored; no dialog was shown.
+ * - `decided`: the user made a choice, which has been saved.
+ * - `dismissed`: the dialog closed without a choice; ads stay gated for this
+ *   session.
+ * - `alreadyPresenting`: a consent dialog is already on screen or being
+ *   prepared.
+ * - `failed`: the dialog could not be shown. `code` is the native
+ *   `EzoicError` code, or `-1` (`'No foreground Activity'`) when the wrapper
+ *   had no foreground Activity / view controller: native was not called, ads
+ *   stay gated, and you should call again once a screen is showing.
+ */
+export type EzoicConsentOutcome =
+  | { type: 'notRequired' }
+  | { type: 'alreadyDecided' }
+  | { type: 'dismissed' }
+  | { type: 'alreadyPresenting' }
+  | { type: 'decided'; decision: EzoicConsentDecision }
+  | { type: 'failed'; code: number; message: string };
+
+const SIMPLE_TYPES = [
+  'notRequired',
+  'alreadyDecided',
+  'dismissed',
+  'alreadyPresenting',
+] as const;
+
+const DECISIONS: readonly string[] = ['acceptAll', 'rejectAll', 'custom'];
+
+export function consentFailure(
+  code: number,
+  message: string
+): EzoicConsentOutcome {
+  return { type: 'failed', code, message };
+}
+
+/**
+ * Maps the native glue's outcome map to `EzoicConsentOutcome`. Anything that
+ * doesn't match the wire format becomes `failed(-1, 'Unrecognized outcome')`.
+ */
+export function parseConsentOutcome(raw: unknown): EzoicConsentOutcome {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const { type, decision, code, message } = raw as Record<string, unknown>;
+    const simple = SIMPLE_TYPES.find((t) => t === type);
+    if (simple) return { type: simple };
+    if (
+      type === 'decided' &&
+      typeof decision === 'string' &&
+      DECISIONS.includes(decision)
+    ) {
+      return { type: 'decided', decision: decision as EzoicConsentDecision };
+    }
+    if (type === 'failed') {
+      return consentFailure(
+        typeof code === 'number' ? code : -1,
+        typeof message === 'string' ? message : 'Unknown error'
+      );
+    }
+  }
+  return consentFailure(-1, 'Unrecognized outcome');
+}

package/src/NativeEzoicAds.ts

@@ -8,6 +8,12 @@ export interface EzoicConfig {
   requestATTBeforeAds?: boolean;
   debugEnabled?: boolean;
   testMode?: boolean;
+  /** Record a pageview automatically on native screen changes. Default `true`. */
+  autoTrackPageviews?: boolean;
+  /** Enable the built-in TCF CMP for GDPR regions. Default `true`; set `false` if you run your own CMP. */
+  cmpEnabled?: boolean;
+  /** Present the consent dialog (if required) right after `initialize` succeeds. Default `true`. */
+  autoPresentConsent?: boolean;
 }
 
 /**
@@ -22,12 +28,31 @@ export interface EzoicRewardResult {
   amount: number;
 }
 
+/**
+ * Wire format of a consent outcome from the native glue (see
+ * `parseConsentOutcome`): `type` is one of `notRequired`, `alreadyDecided`,
+ * `dismissed`, `alreadyPresenting`, `decided` (with `decision`) or `failed`
+ * (with `code` and `message`).
+ */
+export interface EzoicConsentOutcomeRaw {
+  type: string;
+  decision?: string;
+  code?: number;
+  message?: string;
+}
+
 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>;
+  trackPageview(screen: string | null): Promise<boolean>;
+  // Consent: the present* promises always resolve (never reject); a missing
+  // host Activity / view controller resolves as failed(-1).
+  presentConsentIfRequired(): Promise<EzoicConsentOutcomeRaw>;
+  presentConsentSettings(): Promise<EzoicConsentOutcomeRaw>;
+  isConsentRequired(): Promise<boolean | null>;
+  resetConsent(): void;
   loadRewardedAd(adUnitIdentifier: string): Promise<void>;
   showRewardedAd(
     adUnitIdentifier: string,

package/src/helpers.ts

@@ -13,6 +13,11 @@ export function normalizeConfig(config: EzoicConfig): EzoicConfig {
     out.requestATTBeforeAds = config.requestATTBeforeAds;
   if (config.debugEnabled !== undefined) out.debugEnabled = config.debugEnabled;
   if (config.testMode !== undefined) out.testMode = config.testMode;
+  if (config.autoTrackPageviews !== undefined)
+    out.autoTrackPageviews = config.autoTrackPageviews;
+  if (config.cmpEnabled !== undefined) out.cmpEnabled = config.cmpEnabled;
+  if (config.autoPresentConsent !== undefined)
+    out.autoPresentConsent = config.autoPresentConsent;
   return out;
 }
 

package/src/index.tsx

@@ -5,8 +5,14 @@ import EzoicBannerNative from './EzoicBannerViewNativeComponent';
 import EzoicNativeAdNative from './EzoicNativeAdViewNativeComponent';
 import EzoicOutstreamNative from './EzoicOutstreamAdViewNativeComponent';
 import { coerceAdUnitId, normalizeConfig, normalizeSize } from './helpers';
+import {
+  consentFailure,
+  parseConsentOutcome,
+  type EzoicConsentOutcome,
+} from './EzoicConsent';
 
 export type { EzoicConfig };
+export type { EzoicConsentDecision, EzoicConsentOutcome } from './EzoicConsent';
 export {
   EzoicRewardedAd,
   type EzoicReward,
@@ -22,6 +28,27 @@ export {
   type EzoicInstreamImpressionOptions,
 } from './EzoicInstreamAd';
 
+/**
+ * Numeric native error codes: `code` on ad-view `onError` events, and
+ * `error.userInfo.code` on rejected rewarded / interstitial / instream
+ * `load()` promises (whose own `code` is the string `'EzoicAds'`).
+ */
+export const EzoicErrorCode = {
+  /**
+   * GDPR applies and the user hasn't decided: the ad load waited for the
+   * consent dialog and timed out. Call `EzoicAds.presentConsentIfRequired()`.
+   */
+  consentRequired: 5001,
+} as const;
+
+function presentConsent(
+  call: () => Promise<unknown>
+): Promise<EzoicConsentOutcome> {
+  return call().then(parseConsentOutcome, (e: unknown) =>
+    consentFailure(-1, e instanceof Error ? e.message : String(e))
+  );
+}
+
 export const EzoicAds = {
   initialize(config: EzoicConfig): Promise<void> {
     return NativeEzoicAds.initialize(normalizeConfig(config));
@@ -35,8 +62,41 @@ export const EzoicAds = {
   setSubjectToCOPPA(value: boolean): void {
     NativeEzoicAds.setSubjectToCOPPA(value);
   },
-  trackPageview(): Promise<boolean> {
-    return NativeEzoicAds.trackPageview();
+  /**
+   * Records a pageview. Pass a `screen` label (e.g. `'Home'`,
+   * `'members/profile'`) to name the screen in Ezoic reporting; without one
+   * the pageview lands on a single app-wide bucket.
+   */
+  trackPageview(screen?: string): Promise<boolean> {
+    return NativeEzoicAds.trackPageview(screen ?? null);
+  },
+  /**
+   * Shows the built-in consent dialog if this user must decide (GDPR applies,
+   * no valid stored decision). Runs automatically after `initialize` unless
+   * `autoPresentConsent: false`; repeat calls are harmless. Always resolves.
+   */
+  presentConsentIfRequired(): Promise<EzoicConsentOutcome> {
+    return presentConsent(() => NativeEzoicAds.presentConsentIfRequired());
+  },
+  /**
+   * Re-opens the consent dialog with the user's stored choices. TCF requires
+   * a persistent "Privacy settings" entry point that calls this. Always
+   * resolves.
+   */
+  presentConsentSettings(): Promise<EzoicConsentOutcome> {
+    return presentConsent(() => NativeEzoicAds.presentConsentSettings());
+  },
+  /**
+   * `true` when GDPR applies and the built-in CMP handles consent, `false`
+   * otherwise, `null` until the init request completes or when the server
+   * sent no consent information.
+   */
+  isConsentRequired(): Promise<boolean | null> {
+    return NativeEzoicAds.isConsentRequired().then((v) => v ?? null);
+  },
+  /** Deletes the decision stored by the built-in CMP so the dialog shows again. */
+  resetConsent(): void {
+    NativeEzoicAds.resetConsent();
   },
 };