@ezoic/react-native-sdk 1.11.1 → 1.13.0

package/EzoicReactNativeSdk.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => min_ios_version_supported }
-  s.source       = { :git => "https://github.com/ezoic/react-native-sdk.git", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/ezoic/react-native-sdk.git", :tag => "v#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"
@@ -20,7 +20,7 @@ Pod::Spec.new do |s|
 
   # Native Ezoic Ads SDK (vends the `EzoicAdsSDKBinary` module). Brings in
   # PrebidMobile + Google-Mobile-Ads-SDK transitively.
-  s.dependency "EzoicAdsSDK", "~> 1.11.0"
+  s.dependency "EzoicAdsSDK", "~> 1.13.0"
   # The native-ad host imports GoogleMobileAds directly (NativeAdView,
   # MediaView, NativeAd). Pin GMA 12 so the module is on the compile path.
   s.dependency "Google-Mobile-Ads-SDK", "~> 12.0"

package/README.md

@@ -11,7 +11,7 @@ for iOS (`EzoicAdsSDK`, via CocoaPods) and Android
 ## Requirements
 
 - React Native 0.76+ with the New Architecture enabled.
-- iOS 15.0+ (Xcode 27 enforces a 15.0 floor), Android `minSdk` 24+.
+- iOS 15.0+ and Xcode 26+ (required by the native `EzoicAdsSDK` 1.13), Android `minSdk` 24+.
 
 ## Installation
 
@@ -41,16 +41,16 @@ cd ios && RCT_NEW_ARCH_ENABLED=1 pod install
 ```tsx
 import { EzoicAds, EzoicBannerView } from '@ezoic/react-native-sdk';
 
-// Initialize once, early in app startup.
+// Initialize once, early in app startup. In GDPR regions the built-in consent
+// dialog is presented automatically once this resolves (see "Privacy & consent").
 await EzoicAds.initialize({ domain: 'example.com' });
 
-// Optional consent / privacy signals.
-EzoicAds.setGDPRConsent(true, '<IAB TCF consent string>');
+// Optional privacy signals.
 EzoicAds.setGPPConsent('<GPP string>', '7');
 EzoicAds.setSubjectToCOPPA(false);
 
-// Track a pageview.
-const tracked = await EzoicAds.trackPageview();
+// Label the current screen in reporting (see "Pageview labelling").
+const tracked = await EzoicAds.trackPageview('Home');
 
 // Render a banner. A hard-coded height is optional: on no-fill the view
 // collapses to height 0 (default), and `onSizeChange` reports the creative
@@ -155,13 +155,248 @@ await instream.destroy();
 already in flight for this id; it is safe to call again after a previous load
 resolves. `contentUrl` and `revenueUsd` are optional.
 
+## Configuration
+
+`EzoicAds.initialize(config)` accepts:
+
+| Field | Default | |
+|---|---|---|
+| `domain` | (required) | Your Ezoic domain. |
+| `autoReadConsent` | `true` | Read `IABTCF_*` / `IABGPP_*` consent keys written by a CMP. |
+| `subjectToCOPPA` | `false` | Treat the user as subject to COPPA. |
+| `requestATTBeforeAds` | `true` | iOS only: request App Tracking Transparency before the first ad. |
+| `debugEnabled` | `false` | Verbose native logging. |
+| `testMode` | `false` | Ezoic $0.00 test ads on debug builds / simulators. Disable before release. |
+| `autoTrackPageviews` | `true` | Record a pageview automatically on native screen changes. See [Pageview labelling](#pageview-labelling). |
+| `cmpEnabled` | `true` | Enable the built-in TCF CMP. Set `false` if you run your own CMP. |
+| `autoPresentConsent` | `true` | Present the consent dialog (if required) right after `initialize` resolves. |
+
+## Privacy & consent
+
+### Built-in CMP (GDPR / TCF 2.4)
+
+The native SDK includes an IAB TCF 2.4 consent management platform (CMP ID
+299). It is on by default (`cmpEnabled: true`) and only does anything for users
+in GDPR regions; elsewhere nothing is shown and ads load as before.
+
+> **If your app already runs another CMP (UMP, OneTrust, …) you _must_ set
+> `cmpEnabled: false`.** See [Using your own CMP](#using-your-own-cmp).
+>
+> **Upgrading from 1.11.x:** `cmpEnabled` and `autoPresentConsent` default to
+> `true`, so GDPR-region users now see the built-in dialog after `initialize`
+> and ad loads wait for their decision. If you pass consent yourself, move
+> `setGDPRConsent` **before** `initialize` (earlier versions of this README
+> showed it after) and set `cmpEnabled: false`; see
+> [Manual consent](#manual-consent).
+
+**The dialog is presented for you.** Once `initialize` resolves, the wrapper
+calls `presentConsentIfRequired()` once on your behalf (`autoPresentConsent:
+true`). Outside GDPR regions, with `cmpEnabled: false`, when another CMP is
+present, when you called `setGDPRConsent` before `initialize`, or with
+`autoReadConsent: false`, the native SDK returns `notRequired` and nothing is
+shown.
+
+In GDPR regions, ad loads wait while the consent dialog is loading or on screen
+(at most 5 minutes in total per dialog), and up to 10 seconds while no dialog is
+in progress, the dialog is covered, or the app is in the background, then fail
+with error code `5001` ([`EzoicErrorCode.consentRequired`](#error-code-5001)).
+If native can't show the dialog at all (e.g. network error), it returns
+`failed` with the native error code and ads proceed without a TC string
+(limited ads). A `failed` outcome with `code: -1` is different: the wrapper had
+no foreground screen to present from, native was never called, and ads stay
+gated (they wait up to 10 seconds, then fail with `5001`).
+
+To control the timing or read the outcome, turn auto-presentation off and call
+`presentConsentIfRequired()` yourself, e.g. from your first screen:
+
+```tsx
+import { EzoicAds } from '@ezoic/react-native-sdk';
+
+await EzoicAds.initialize({ domain: 'example.com', autoPresentConsent: false });
+
+const outcome = await EzoicAds.presentConsentIfRequired();
+switch (outcome.type) {
+  case 'decided':
+    console.log('User chose', outcome.decision); // 'acceptAll' | 'rejectAll' | 'custom'
+    break;
+  case 'failed':
+    console.log('Consent UI failed', outcome.code, outcome.message);
+    break;
+  default:
+    break; // 'notRequired' | 'alreadyDecided' | 'dismissed' | 'alreadyPresenting'
+}
+```
+
+`presentConsentIfRequired()` can be called at any time, and repeat calls are
+harmless: you get `alreadyPresenting` while a dialog is in flight and
+`alreadyDecided` once a valid decision is stored. Re-present whenever
+`isConsentRequired()` is `true` and no decision has been made (e.g. after
+`dismissed` or `failed`). Called before initialization finishes, it waits for
+the init response. If `initialize` resolves before any screen is showing (no
+foreground Activity on Android, no presented view controller on iOS, e.g. a very
+early cold start), the automatic presentation is skipped; call
+`presentConsentIfRequired()` from your first screen.
+
+The promise always resolves (never rejects) with an `EzoicConsentOutcome`:
+
+| `type` | When |
+|---|---|
+| `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 shown |
+| `decided` | The user chose `decision` (`acceptAll`, `rejectAll` or `custom`); the choice is 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 couldn't be shown. `code`/`message` come from the native error. `code: -1` with `message: 'No foreground Activity'` (on both platforms) is wrapper-side: there was no foreground Activity / view controller, native was not called and ads stay gated, so call `presentConsentIfRequired()` again once a screen is showing |
+
+- **`isConsentRequired()`** resolves `true` whenever GDPR applies and the
+  built-in CMP is in charge (including after the user has decided), `false`
+  otherwise, and `null` until the init request completes or when the server
+  sent no consent information.
+- **`resetConsent()`** deletes the stored decision so the dialog shows again
+  (ads re-gate until the user decides).
+
+### Privacy settings button (required)
+
+TCF policy requires users to be able to reopen the dialog and change or
+withdraw consent at any time. Wire `presentConsentSettings()` to a menu item or
+button that is always reachable:
+
+```tsx
+<Button
+  title="Privacy settings"
+  onPress={() => EzoicAds.presentConsentSettings()}
+/>
+```
+
+It reopens the dialog with the user's stored choices in GDPR regions and
+resolves `notRequired` elsewhere, with `cmpEnabled: false`, or when another CMP
+is present.
+
+### Using your own CMP
+
+Set `cmpEnabled: false`. The SDK then reads your CMP's `IABTCF_*` (TCF) and
+`IABGPP_*` (GPP) keys exactly as before. The built-in CMP also stays out of the
+way automatically if it finds `IABTCF_CmpSdkID` set to another CMP's ID.
+
+```tsx
+await EzoicAds.initialize({ domain: 'example.com', cmpEnabled: false });
+```
+
+### Manual consent
+
+`setGDPRConsent` and the built-in CMP are mutually exclusive. The override
+lasts for the current process only, so **call `setGDPRConsent` before
+`initialize` on every launch** (or set `cmpEnabled: false`). Otherwise each cold
+start begins with the built-in CMP in charge until your call lands: it can gate
+ad loads, show its dialog and write `IABTCF_*` keys. The SDK doesn't write your
+consent string to `IABTCF_*` keys for other SDKs, so your own CMP must do that.
+
+```tsx
+EzoicAds.setGDPRConsent(true, '<IAB TCF consent string>');
+await EzoicAds.initialize({ domain: 'example.com', cmpEnabled: false });
+```
+
+### Error code 5001
+
+When GDPR applies and the user hasn't decided, ad loads fail after the wait
+described above with code `5001`, exported as `EzoicErrorCode.consentRequired`.
+Consent is checked when an ad loads, so the code arrives as:
+
+- `code` on the ad views' `onError` (banner, native, outstream);
+- `error.userInfo.code` on rejected rewarded, interstitial and instream
+  `load()` promises. The rejection's own `code` stays the string `'EzoicAds'`
+  and its `message` is the native one ("User consent is required to load
+  ads.").
+
+```tsx
+import {
+  EzoicAds,
+  EzoicBannerView,
+  EzoicErrorCode,
+  EzoicRewardedAd,
+} from '@ezoic/react-native-sdk';
+
+<EzoicBannerView
+  adUnitIdentifier="123456"
+  onError={(e) => {
+    if (e.code === EzoicErrorCode.consentRequired) {
+      // The user hasn't decided yet; e.g. offer EzoicAds.presentConsentIfRequired().
+    }
+  }}
+/>;
+
+try {
+  const ad = await EzoicRewardedAd.load('123456');
+  await ad.show();
+} catch (e: any) {
+  if (e?.userInfo?.code === EzoicErrorCode.consentRequired) {
+    await EzoicAds.presentConsentIfRequired();
+  }
+}
+```
+
+## Pageview labelling
+
+Ezoic reports app traffic per *screen*, the way it reports a site per URL. Apps
+have no URLs, so the SDK builds one from a label:
+`https://<your domain>/<bundle id>/<screen label>`.
+
+The native SDK tracks pageviews automatically, but it only sees native screens:
+in a React Native app that is the single host Activity / view controller, so
+every JS screen lands in one bucket. Call `trackPageview(screen)` when the user
+reaches a screen to give it a name. With React Navigation, do it from the
+container's `onStateChange`:
+
+```tsx
+import { useRef } from 'react';
+import {
+  NavigationContainer,
+  useNavigationContainerRef,
+} from '@react-navigation/native';
+import { EzoicAds } from '@ezoic/react-native-sdk';
+
+export default function App() {
+  const navigationRef = useNavigationContainerRef();
+  const lastRouteName = useRef<string | undefined>(undefined);
+  const trackCurrentRoute = () => {
+    const name = navigationRef.getCurrentRoute()?.name;
+    if (name && name !== lastRouteName.current) {
+      lastRouteName.current = name;
+      EzoicAds.trackPageview(name);
+    }
+  };
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      onReady={trackCurrentRoute}
+      onStateChange={trackCurrentRoute}
+    >
+      {/* ... */}
+    </NavigationContainer>
+  );
+}
+```
+
+Labels are free text: use `/` for hierarchy (`members/profile`), spaces become
+`-`, punctuation is dropped, case is kept. The label is also attached to every
+ad request on that screen until the next pageview. A labelled pageview takes
+precedence over the automatic one for the same navigation, so there is no
+double counting. If you label every screen, set `autoTrackPageviews: false` so
+pageviews come only from your calls. `trackPageview()` without a label records
+an unlabelled pageview.
+
 ## API
 
-- `EzoicAds.initialize(config)` → `Promise<void>`
-- `EzoicAds.setGDPRConsent(applies, consentString?)` → `void`
+- `EzoicAds.initialize(config)` → `Promise<void>` (see [Configuration](#configuration))
+- `EzoicAds.setGDPRConsent(applies, consentString?)` → `void` (call before `initialize`)
 - `EzoicAds.setGPPConsent(gppString?, sectionIds?)` → `void`
 - `EzoicAds.setSubjectToCOPPA(value)` → `void`
-- `EzoicAds.trackPageview()` → `Promise<boolean>`
+- `EzoicAds.trackPageview(screen?)` → `Promise<boolean>`
+- `EzoicAds.presentConsentIfRequired()` → `Promise<EzoicConsentOutcome>`
+- `EzoicAds.presentConsentSettings()` → `Promise<EzoicConsentOutcome>`
+- `EzoicAds.isConsentRequired()` → `Promise<boolean | null>`
+- `EzoicAds.resetConsent()` → `void`
+- `EzoicErrorCode.consentRequired` = `5001`
 - `<EzoicBannerView adUnitIdentifier size collapseOnNoFill onSizeChange onLoad onError onImpression onClick onOpen onClose />`
 - `<EzoicNativeAdView adUnitIdentifier onLoad onError onImpression onClick onOpen onClose />`
 - `<EzoicOutstreamAdView adUnitIdentifier collapseOnNoFill onSizeChange onLoad onError onImpression onClick onOpen onClose />`

package/android/build.gradle

@@ -68,7 +68,7 @@ dependencies {
   // Native Ezoic Ads SDK (resolved from Maven Central). Brings in Google Mobile
   // Ads + Prebid transitively. Requires mavenCentral() + google() in the
   // consuming app's repositories (the RN template provides both).
-  implementation "com.ezoic.sdk:ezoic-ads-sdk:1.11.0"
+  implementation "com.ezoic.sdk:ezoic-ads-sdk:1.13.0"
 
   // The native-ad wrapper references GMA's NativeAdView/MediaView/NativeAd
   // types at compile time. The Ezoic SDK POM scopes Google Mobile Ads at

package/android/src/main/java/com/ezoic/reactnative/EzoicAdsModule.kt

@@ -1,10 +1,13 @@
 package com.ezoic.reactnative
 
+import android.app.Activity
 import android.app.Application
+import android.util.Log
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.ezoic.ads.sdk.adunits.EzoicInstreamAd
@@ -19,6 +22,8 @@ import com.ezoic.ads.sdk.adunits.EzoicRewardedAdListenerAdapter
 import com.ezoic.ads.sdk.core.EzoicAds
 import com.ezoic.ads.sdk.core.EzoicConfiguration
 import com.ezoic.ads.sdk.core.EzoicError
+import com.ezoic.ads.sdk.privacy.cmp.ConsentDecisionType
+import com.ezoic.ads.sdk.privacy.cmp.ConsentOutcome
 import java.util.concurrent.ConcurrentHashMap
 import java.util.concurrent.atomic.AtomicBoolean
 
@@ -93,11 +98,35 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
       subjectToCOPPA = config.optBool("subjectToCOPPA", false),
       requestATTBeforeAds = config.optBool("requestATTBeforeAds", true),
       debugEnabled = config.optBool("debugEnabled", false),
-      testMode = config.optBool("testMode", false)
+      testMode = config.optBool("testMode", false),
+      autoTrackPageviews = config.optBool("autoTrackPageviews", true),
+      cmpEnabled = config.optBool("cmpEnabled", true)
     )
+    val autoPresentConsent = config.optBool("autoPresentConsent", true)
     EzoicAds.instance.initialize(app, configuration) { result ->
-      result.onSuccess { promise.resolve(null) }
-        .onFailure { e -> promise.reject("EzoicAds", e.message, e) }
+      result.onSuccess {
+        promise.resolve(null)
+        if (autoPresentConsent) presentConsentAfterInit(configuration.debugEnabled)
+      }.onFailure { e -> promise.reject("EzoicAds", e.message, e) }
+    }
+  }
+
+  /**
+   * Presents the consent dialog once after a successful `initialize`. Native
+   * returns `NotRequired` outside GDPR / with `cmpEnabled = false` / with
+   * another CMP or manual consent, so this is a no-op there. The outcome is
+   * only logged; publishers wanting it call `presentConsentIfRequired`.
+   */
+  private fun presentConsentAfterInit(debug: Boolean) {
+    val activity = currentActivity
+    if (activity == null) {
+      if (debug) Log.d(NAME, "autoPresentConsent skipped: no foreground Activity")
+      return
+    }
+    activity.runOnUiThread {
+      EzoicAds.instance.presentConsentIfRequired(activity) { outcome ->
+        if (debug) Log.d(NAME, "autoPresentConsent outcome: $outcome")
+      }
     }
   }
 
@@ -113,8 +142,50 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
     EzoicAds.instance.setSubjectToCOPPA(value)
   }
 
-  override fun trackPageview(promise: Promise) {
-    EzoicAds.instance.trackPageview { success -> promise.resolve(success) }
+  override fun trackPageview(screen: String?, promise: Promise) {
+    if (screen.isNullOrEmpty()) {
+      EzoicAds.instance.trackPageview { success -> promise.resolve(success) }
+    } else {
+      EzoicAds.instance.trackPageview(screen) { success -> promise.resolve(success) }
+    }
+  }
+
+  override fun presentConsentIfRequired(promise: Promise) {
+    presentConsent(promise) { activity, callback ->
+      EzoicAds.instance.presentConsentIfRequired(activity, callback)
+    }
+  }
+
+  override fun presentConsentSettings(promise: Promise) {
+    presentConsent(promise) { activity, callback ->
+      EzoicAds.instance.presentConsentSettings(activity, callback)
+    }
+  }
+
+  override fun isConsentRequired(promise: Promise) {
+    UiThreadUtil.runOnUiThread { promise.resolve(EzoicAds.instance.isConsentRequired) }
+  }
+
+  override fun resetConsent() {
+    UiThreadUtil.runOnUiThread { EzoicAds.instance.resetConsent() }
+  }
+
+  /**
+   * Presents from the foreground Activity on the UI thread and always resolves
+   * with an outcome map; with no Activity it resolves `failed(-1)`.
+   */
+  private fun presentConsent(
+    promise: Promise,
+    present: (Activity, (ConsentOutcome) -> Unit) -> Unit
+  ) {
+    val activity = currentActivity
+    if (activity == null) {
+      promise.resolve(consentFailureMap(NO_ACTIVITY_CODE, NO_ACTIVITY_MESSAGE))
+      return
+    }
+    activity.runOnUiThread {
+      present(activity) { outcome -> promise.resolve(outcome.toWritableMap()) }
+    }
   }
 
   override fun loadRewardedAd(adUnitIdentifier: String, promise: Promise) {
@@ -134,7 +205,7 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
         rewardedAds[id] = ad
         promise.resolve(null)
       }.onFailure { e ->
-        promise.reject("EzoicAds", e.message ?: "Rewarded ad failed to load", e)
+        promise.rejectLoad(e, "Rewarded ad failed to load")
       }
     }
   }
@@ -216,7 +287,7 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
         interstitialAds[id] = ad
         promise.resolve(null)
       }.onFailure { e ->
-        promise.reject("EzoicAds", e.message ?: "Interstitial ad failed to load", e)
+        promise.rejectLoad(e, "Interstitial ad failed to load")
       }
     }
   }
@@ -305,9 +376,7 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
       override fun onAdFailedToLoad(error: EzoicError) {
         if (holder.settled.compareAndSet(false, true)) {
           loadingInstream.remove(id)
-          val userInfo = Arguments.createMap()
-          userInfo.putInt("code", error.code)
-          promise.reject("EzoicAds", error.message ?: "Instream ad failed to load", userInfo)
+          promise.rejectLoad(error, "Instream ad failed to load")
         }
       }
     })
@@ -477,11 +546,52 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
       .emit(INTERSTITIAL_EVENT, map)
   }
 
+  /**
+   * Rejects a load with the string code "EzoicAds" and, for native errors, the
+   * numeric `EzoicError.code` in `userInfo` (JS: `error.userInfo.code`).
+   */
+  private fun Promise.rejectLoad(e: Throwable, fallbackMessage: String) {
+    val userInfo = (e as? EzoicError)?.let { error ->
+      Arguments.createMap().apply { putInt("code", error.code) }
+    }
+    reject("EzoicAds", e.message ?: fallbackMessage, e, userInfo)
+  }
+
+  private fun consentFailureMap(code: Int, message: String): WritableMap =
+    Arguments.createMap().apply {
+      putString("type", "failed")
+      putInt("code", code)
+      putString("message", message)
+    }
+
+  private fun ConsentOutcome.toWritableMap(): WritableMap = when (this) {
+    ConsentOutcome.NotRequired -> consentTypeMap("notRequired")
+    ConsentOutcome.AlreadyDecided -> consentTypeMap("alreadyDecided")
+    ConsentOutcome.Dismissed -> consentTypeMap("dismissed")
+    ConsentOutcome.AlreadyPresenting -> consentTypeMap("alreadyPresenting")
+    is ConsentOutcome.Decided -> consentTypeMap("decided").apply {
+      putString(
+        "decision",
+        when (decision) {
+          ConsentDecisionType.ACCEPT_ALL -> "acceptAll"
+          ConsentDecisionType.REJECT_ALL -> "rejectAll"
+          ConsentDecisionType.CUSTOM -> "custom"
+        }
+      )
+    }
+    is ConsentOutcome.Failed -> consentFailureMap(error.code, error.message)
+  }
+
+  private fun consentTypeMap(type: String): WritableMap =
+    Arguments.createMap().apply { putString("type", type) }
+
   private fun ReadableMap.optBool(key: String, default: Boolean): Boolean =
     if (hasKey(key) && !isNull(key)) getBoolean(key) else default
 
   companion object {
     const val NAME = NativeEzoicAdsSpec.NAME
+    private const val NO_ACTIVITY_CODE = -1
+    private const val NO_ACTIVITY_MESSAGE = "No foreground Activity"
     private const val REWARDED_EVENT = "EzoicRewardedAdEvent"
     private const val INTERSTITIAL_EVENT = "EzoicInterstitialAdEvent"
   }