@ezoic/react-native-sdk 1.3.0 → 1.5.0

package/EzoicReactNativeSdk.podspec

@@ -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.3"
+  s.dependency "EzoicAdsSDK", "~> 1.5"
   # 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

@@ -1,12 +1,12 @@
 # @ezoic/react-native-sdk
 
-Ezoic Ads SDK for React Native (Prebid + Google Ad Manager banner, native, interstitial and rewarded ads).
+Ezoic Ads SDK for React Native (Prebid + Google Ad Manager banner, native, interstitial, rewarded, outstream and instream video ads).
 
 A thin React Native (New Architecture) wrapper over the native Ezoic Ads SDKs
 for iOS (`EzoicAdsSDK`, via CocoaPods) and Android
 (`com.ezoic.sdk:ezoic-ads-sdk`, via Maven Central). It exposes an imperative
-`EzoicAds` TurboModule plus `EzoicBannerView` and `EzoicNativeAdView` Fabric
-components.
+`EzoicAds` TurboModule plus `EzoicBannerView`, `EzoicNativeAdView` and
+`EzoicOutstreamAdView` Fabric components, and the `EzoicInstreamAd` controller.
 
 ## Requirements
 
@@ -91,6 +91,60 @@ import { EzoicAds, EzoicNativeAdView } from '@ezoic/react-native-sdk';
 />;
 ```
 
+### Outstream video
+
+`EzoicOutstreamAdView` loads and renders a self-contained outstream video ad.
+Like the native ad it has no `size` prop — size it with `style` and the native
+view lays the player out inside those bounds. It is view-managed: mounting the
+component loads the ad, unmounting destroys it.
+
+```tsx
+import { EzoicAds, EzoicOutstreamAdView } from '@ezoic/react-native-sdk';
+
+<EzoicOutstreamAdView
+  adUnitIdentifier="123456"
+  style={{ width: '100%', height: 250 }}
+  onLoad={() => console.log('loaded')}
+  onError={(e) => console.log('error', e.message, e.code)}
+  onImpression={() => console.log('impression')}
+  onClick={() => console.log('click')}
+  onOpen={() => console.log('open')}
+  onClose={() => console.log('close')}
+/>;
+```
+
+### Instream video
+
+`EzoicInstreamAd` is a view-less controller for instream (pre/mid/post-roll)
+video. **The host owns the video player and the Google IMA SDK** — the SDK
+renders nothing; its sole deliverable is a GAM VAST ad-tag URL string you feed
+to your own IMA `AdsRequest`. A controller is multi-use and prefetchable: it is
+not auto-destroyed, so you `load()` it repeatedly and `destroy()` it yourself.
+
+```tsx
+import { EzoicInstreamAd } from '@ezoic/react-native-sdk';
+
+const instream = new EzoicInstreamAd('123456');
+
+// Resolve the VAST ad-tag URL and hand it to your IMA player.
+const adTagUrl = await instream.load({ contentUrl: playingVideoUrl });
+adsLoader.requestAds({ adTagUrl });
+
+// On an IMA ad error, walk down the floor waterfall to the next tag.
+const next = await instream.getNextAdTagUrl(); // null once exhausted
+if (next) adsLoader.requestAds({ adTagUrl: next });
+
+// On the IMA STARTED event, fire the Ezoic impression pixel.
+await instream.reportImpression({ revenueUsd: 0.012 });
+
+// Release the native controller when done.
+await instream.destroy();
+```
+
+`load()` rejects on no fill, an uninitialized SDK, or an overlapping load
+already in flight for this id; it is safe to call again after a previous load
+resolves. `contentUrl` and `revenueUsd` are optional.
+
 ## API
 
 - `EzoicAds.initialize(config)` → `Promise<void>`
@@ -100,6 +154,12 @@ import { EzoicAds, EzoicNativeAdView } from '@ezoic/react-native-sdk';
 - `EzoicAds.trackPageview()` → `Promise<boolean>`
 - `<EzoicBannerView adUnitIdentifier size onLoad onError onImpression onClick onOpen onClose />`
 - `<EzoicNativeAdView adUnitIdentifier onLoad onError onImpression onClick onOpen onClose />`
+- `<EzoicOutstreamAdView adUnitIdentifier onLoad onError onImpression onClick onOpen onClose />`
+- `new EzoicInstreamAd(adUnitIdentifier)`
+  - `.load({ contentUrl? })` → `Promise<string>` (GAM VAST ad-tag URL)
+  - `.getNextAdTagUrl()` → `Promise<string | null>`
+  - `.reportImpression({ revenueUsd? })` → `Promise<void>`
+  - `.destroy()` → `Promise<void>`
 
 ## License
 

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.3.0"
+  implementation "com.ezoic.sdk:ezoic-ads-sdk:1.5.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

@@ -7,6 +7,8 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.ezoic.ads.sdk.adunits.EzoicInstreamAd
+import com.ezoic.ads.sdk.adunits.EzoicInstreamAdListener
 import com.ezoic.ads.sdk.adunits.EzoicInterstitialAd
 import com.ezoic.ads.sdk.adunits.EzoicInterstitialAdListener
 import com.ezoic.ads.sdk.adunits.EzoicInterstitialAdListenerAdapter
@@ -18,6 +20,7 @@ import com.ezoic.ads.sdk.core.EzoicAds
 import com.ezoic.ads.sdk.core.EzoicConfiguration
 import com.ezoic.ads.sdk.core.EzoicError
 import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
 
 class EzoicAdsModule(reactContext: ReactApplicationContext) :
   NativeEzoicAdsSpec(reactContext) {
@@ -51,6 +54,28 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
   /** Ad unit ids with an in-flight interstitial `load`. */
   private val loadingInterstitial = ConcurrentHashMap.newKeySet<Int>()
 
+  /**
+   * Instream controllers, keyed by ad unit id. Instream is multi-use and
+   * prefetchable, so a controller is created-or-reused per id and NOT
+   * auto-destroyed — it lives until [destroyInstreamAd] or module teardown.
+   */
+  private val instreamAds = ConcurrentHashMap<Int, EzoicInstreamAd>()
+
+  /**
+   * In-flight instream `load` calls, keyed by ad unit id. Doubles as the
+   * duplicate-load guard: the native `load` is a SILENT no-op while already
+   * loading, so an overlapping load must be rejected here or its promise hangs
+   * forever.
+   */
+  private val loadingInstream = ConcurrentHashMap<Int, InstreamLoad>()
+
+  private class InstreamLoad(val promise: Promise) {
+    // destroy/invalidate run on the JS thread while listener callbacks run on
+    // main, so settling must be an atomic claim (compareAndSet) rather than a
+    // check-then-set, or both sides can settle the same promise.
+    val settled = AtomicBoolean(false)
+  }
+
   override fun initialize(config: ReadableMap, promise: Promise) {
     val domain = if (config.hasKey("domain")) config.getString("domain") else null
     if (domain.isNullOrEmpty()) {
@@ -235,6 +260,110 @@ class EzoicAdsModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun loadInstreamAd(adUnitIdentifier: Double, contentUrl: String?, promise: Promise) {
+    val id = adUnitIdentifier.toInt()
+    if (id <= 0) {
+      promise.reject("EzoicAds", "Invalid adUnitIdentifier: $adUnitIdentifier")
+      return
+    }
+    // Reject overlapping loads for this id: the native load silently no-ops
+    // while loading (a second load on the reused controller, or a load from a
+    // fresh JS instance sharing the id), which would hang the promise.
+    if (loadingInstream.containsKey(id)) {
+      promise.reject("EzoicAds", "An instream ad is already loading for ad unit $id")
+      return
+    }
+
+    // Create-or-reuse: instream is multi-use, so a repeat load on the same id
+    // reuses the existing native controller (preserving its tag/waterfall state).
+    val ad = instreamAds.getOrPut(id) { EzoicInstreamAd(id) }
+
+    val holder = InstreamLoad(promise)
+    loadingInstream[id] = holder
+    // The native load uses the context only for parity (it is not retained);
+    // pass the same reactApplicationContext the rewarded/interstitial loads use.
+    // The native SDK already posts these callbacks to main, so settle directly
+    // here — no need to re-post via a Handler.
+    ad.load(reactApplicationContext, contentUrl, object : EzoicInstreamAdListener {
+      override fun onAdTagReady(adTagUrl: String) {
+        // CAS guard: after a destroy->reload a stale callback must not evict
+        // the newer load's holder (only the winning settle removes it).
+        if (holder.settled.compareAndSet(false, true)) {
+          loadingInstream.remove(id)
+          promise.resolve(adTagUrl)
+        }
+      }
+
+      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)
+        }
+      }
+    })
+  }
+
+  override fun getInstreamNextAdTagUrl(adUnitIdentifier: Double, promise: Promise) {
+    val id = adUnitIdentifier.toInt()
+    if (id <= 0) {
+      promise.reject("EzoicAds", "Invalid adUnitIdentifier: $adUnitIdentifier")
+      return
+    }
+    // Synchronous native call; resolves the next waterfall tag or null when
+    // exhausted / before a successful load / after destroy.
+    promise.resolve(instreamAds[id]?.getNextAdTagUrl())
+  }
+
+  override fun reportInstreamImpression(
+    adUnitIdentifier: Double,
+    revenueUsd: Double?,
+    promise: Promise
+  ) {
+    val id = adUnitIdentifier.toInt()
+    if (id <= 0) {
+      promise.reject("EzoicAds", "Invalid adUnitIdentifier: $adUnitIdentifier")
+      return
+    }
+    // No-op natively when no tag has been delivered or after destroy.
+    instreamAds[id]?.reportImpression(revenueUsd)
+    promise.resolve(null)
+  }
+
+  override fun destroyInstreamAd(adUnitIdentifier: Double, promise: Promise) {
+    val id = adUnitIdentifier.toInt()
+    if (id <= 0) {
+      promise.reject("EzoicAds", "Invalid adUnitIdentifier: $adUnitIdentifier")
+      return
+    }
+    // The native SDK suppresses load callbacks once destroyed (load tokens), so
+    // settle any pending load's promise HERE first or it hangs forever. The CAS
+    // claim also disarms a listener callback racing in on main concurrently.
+    val pending = loadingInstream.remove(id)
+    if (pending != null && pending.settled.compareAndSet(false, true)) {
+      pending.promise.reject("EzoicAds", "Instream ad was destroyed while loading")
+    }
+    instreamAds.remove(id)?.destroy()
+    promise.resolve(null)
+  }
+
+  override fun invalidate() {
+    // Module teardown: settle every pending instream load with an error and
+    // destroy every controller so no promise hangs and no native resource leaks.
+    for ((_, holder) in loadingInstream) {
+      if (holder.settled.compareAndSet(false, true)) {
+        holder.promise.reject("EzoicAds", "Module was destroyed while loading")
+      }
+    }
+    loadingInstream.clear()
+    for ((_, ad) in instreamAds) {
+      ad.destroy()
+    }
+    instreamAds.clear()
+    super.invalidate()
+  }
+
   override fun addListener(eventName: String) {
     // No-op: required by the React Native NativeEventEmitter contract.
   }

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

@@ -0,0 +1,191 @@
+package com.ezoic.reactnative
+
+import android.content.Context
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.uimanager.events.RCTEventEmitter
+import com.ezoic.ads.sdk.adunits.EzoicOutstreamAdView
+import com.ezoic.ads.sdk.adunits.EzoicOutstreamAdViewListener
+import com.ezoic.ads.sdk.core.EzoicError
+
+/**
+ * Fabric view manager for the outstream video component. Mirrors
+ * [EzoicNativeAdViewManager] exactly (deferred load, load guards, teardown,
+ * manual measure/layout fix, bubbling-event registry) and differs only in the
+ * body of [maybeLoad]: the native [EzoicOutstreamAdView] is itself the rendered
+ * view (a `FrameLayout` that attaches its own GAM `AdManagerAdView`), so this
+ * manager adds that native view as the container's child and lets it render —
+ * there is no template to build as the native-ad manager does.
+ */
+@ReactModule(name = EzoicOutstreamAdViewManager.NAME)
+class EzoicOutstreamAdViewManager(private val ctx: ReactApplicationContext) :
+  SimpleViewManager<EzoicOutstreamAdViewManager.OutstreamAdContainer>() {
+
+  override fun getName() = NAME
+
+  override fun createViewInstance(reactContext: ThemedReactContext): OutstreamAdContainer {
+    val container = OutstreamAdContainer(reactContext)
+    container.layoutParams = ViewGroup.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT
+    )
+    return container
+  }
+
+  @ReactProp(name = "adUnitIdentifier")
+  fun setAdUnitIdentifier(view: OutstreamAdContainer, value: String?) {
+    val newAdUnitId = value?.toIntOrNull() ?: 0
+    // Ad unit changed after a load already started: tear down the loaded/loading
+    // ad and clear the started flag so onAfterUpdateTransaction's maybeLoad
+    // starts a fresh load for the new id.
+    if (newAdUnitId != view.adUnitId && view.loadStarted) {
+      view.ezoicOutstreamAd?.destroy()
+      view.ezoicOutstreamAd = null
+      view.removeAllViews()
+      view.loadStarted = false
+      view.loadGeneration++
+    }
+    view.adUnitId = newAdUnitId
+    view.rawAdUnitId = value ?: ""
+  }
+
+  // Fabric sets every prop for the mount transaction before this runs, so the
+  // ad unit id is final here. `view.post` escapes the mount transaction so the
+  // synchronous native-SDK failure path (uninitialized) can't reenter the
+  // mounting layer; the started flag survives repeated transactions.
+  override fun onAfterUpdateTransaction(view: OutstreamAdContainer) {
+    super.onAfterUpdateTransaction(view)
+    view.post { maybeLoad(view) }
+  }
+
+  private fun maybeLoad(view: OutstreamAdContainer) {
+    if (view.loadStarted || view.disposed) return
+    if (view.adUnitId <= 0) {
+      // Non-numeric or missing id coerces to 0 in setAdUnitIdentifier. Only
+      // emit an error when a prop was actually supplied (non-empty raw
+      // string); an unset prop should stay silent.
+      if (view.rawAdUnitId.isNotEmpty()) {
+        view.loadStarted = true
+        emit(view, "topError", errorMap("Invalid ad unit identifier", 0))
+      }
+      return
+    }
+    view.loadStarted = true
+    val generation = view.loadGeneration
+    // The native outstream view renders itself. Attach the listener BEFORE
+    // loadAd() so no early lifecycle callback is missed, add it to the
+    // container, then load.
+    val outstreamAd = EzoicOutstreamAdView(view.context, view.adUnitId)
+    outstreamAd.listener = object : EzoicOutstreamAdViewListener {
+      override fun onOutstreamLoaded(adView: EzoicOutstreamAdView) {
+        // dispose() and this callback both arrive on the main thread, so the
+        // check is race-free. A generation mismatch means the ad unit changed
+        // mid-load (mirrors the SDK's isCurrentLoad token pattern): emit nothing.
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topLoad", Arguments.createMap())
+      }
+
+      override fun onOutstreamLoadFailed(adView: EzoicOutstreamAdView, error: EzoicError) {
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topError", errorMap(error.message, error.code))
+      }
+
+      override fun onOutstreamImpression(adView: EzoicOutstreamAdView) {
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topImpression", Arguments.createMap())
+      }
+
+      override fun onOutstreamClicked(adView: EzoicOutstreamAdView) {
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topAdClick", Arguments.createMap())
+      }
+
+      override fun onOutstreamOpened(adView: EzoicOutstreamAdView) {
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topOpen", Arguments.createMap())
+      }
+
+      override fun onOutstreamClosed(adView: EzoicOutstreamAdView) {
+        if (view.disposed || view.loadGeneration != generation) return
+        emit(view, "topClose", Arguments.createMap())
+      }
+    }
+    view.ezoicOutstreamAd = outstreamAd
+    view.removeAllViews()
+    view.addView(outstreamAd)
+    outstreamAd.loadAd()
+  }
+
+  override fun onDropViewInstance(view: OutstreamAdContainer) {
+    super.onDropViewInstance(view)
+    view.disposed = true
+    view.loadGeneration++
+    view.ezoicOutstreamAd?.destroy()
+    view.ezoicOutstreamAd = null
+    view.removeAllViews()
+  }
+
+  private fun emit(view: OutstreamAdContainer, event: String, payload: WritableMap) {
+    if (view.disposed) return
+    ctx.getJSModule(RCTEventEmitter::class.java).receiveEvent(view.id, event, payload)
+  }
+
+  private fun errorMap(message: String?, code: Int): WritableMap {
+    val map = Arguments.createMap()
+    map.putString("message", message ?: "")
+    map.putInt("code", code)
+    return map
+  }
+
+  override fun getExportedCustomBubblingEventTypeConstants(): Map<String, Any> {
+    fun reg(on: String) = mapOf("phasedRegistrationNames" to mapOf("bubbled" to on))
+    return mapOf(
+      "topLoad" to reg("onLoad"),
+      "topError" to reg("onError"),
+      "topImpression" to reg("onImpression"),
+      "topAdClick" to reg("onAdClick"),
+      "topOpen" to reg("onOpen"),
+      "topClose" to reg("onClose")
+    )
+  }
+
+  /**
+   * Container for the native outstream view. RN lays out only Yoga-managed
+   * views; the native [EzoicOutstreamAdView] is added from native code and stays
+   * unmeasured (blank) unless we force a measure/layout pass. Overriding
+   * [requestLayout] to post a manual measure(EXACTLY)+layout of the current
+   * bounds is the proven fix (identical to [EzoicNativeAdViewManager]).
+   */
+  class OutstreamAdContainer(context: Context) : FrameLayout(context) {
+    var adUnitId: Int = 0
+    var rawAdUnitId: String = ""
+    var loadStarted: Boolean = false
+    var disposed: Boolean = false
+    var loadGeneration: Int = 0
+    var ezoicOutstreamAd: EzoicOutstreamAdView? = null
+
+    private val measureAndLayout = Runnable {
+      measure(
+        View.MeasureSpec.makeMeasureSpec(width, View.MeasureSpec.EXACTLY),
+        View.MeasureSpec.makeMeasureSpec(height, View.MeasureSpec.EXACTLY)
+      )
+      layout(left, top, right, bottom)
+    }
+
+    override fun requestLayout() {
+      super.requestLayout()
+      post(measureAndLayout)
+    }
+  }
+
+  companion object {
+    const val NAME = "EzoicOutstreamAdView"
+  }
+}

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

@@ -21,7 +21,8 @@ class EzoicReactNativeSdkPackage : BaseReactPackage() {
   ): List<ViewManager<*, *>> {
     return listOf(
       EzoicBannerViewManager(reactContext),
-      EzoicNativeAdViewManager(reactContext)
+      EzoicNativeAdViewManager(reactContext),
+      EzoicOutstreamAdViewManager(reactContext)
     )
   }
 

package/ios/EzoicAdsImpl.swift

@@ -43,6 +43,28 @@ import EzoicAdsSDKBinary
   /// Ad unit ids with an in-flight interstitial `load`.
   private var loadingInterstitial: Set<Int> = []
 
+  /// Active instream controllers, keyed by ad unit id. Instream is multi-use and
+  /// NOT auto-destroying, so this impl retains each controller across load
+  /// cycles (and is its `weak` delegate) until `destroyInstreamAd`.
+  private var instreamAds: [Int: EzoicInstreamAd] = [:]
+
+  /// In-flight instream `load` calls, keyed by ad unit id. Doubles as the
+  /// duplicate-load guard: the native `load` is a silent no-op while already
+  /// loading, so an unguarded second promise would hang forever.
+  private var pendingInstreamLoads: [Int: PendingInstreamLoad] = [:]
+
+  private final class PendingInstreamLoad {
+    let resolve: (Any?) -> Void
+    let reject: (String, String, NSError?) -> Void
+    /// Set once the promise is fulfilled so a late delegate callback (or a
+    /// destroy that already settled it) cannot double-settle it.
+    var settled: Bool = false
+    init(resolve: @escaping (Any?) -> Void, reject: @escaping (String, String, NSError?) -> Void) {
+      self.resolve = resolve
+      self.reject = reject
+    }
+  }
+
   /// Runs `work` on the main thread. The ad/pending/loading dictionaries and
   /// every native load/show call touch UIKit and this shared state, so they must
   /// only run on main. Delegate callbacks already arrive on main.
@@ -228,6 +250,113 @@ import EzoicAdsSDKBinary
     for (key, value) in extra { body[key] = value }
     eventEmitter?("EzoicInterstitialAdEvent", body)
   }
+
+  // MARK: - Instream video
+
+  /// Converts a bridge `Double` ad unit id to a native `Int`, rejecting NaN,
+  /// infinite, and out-of-`Int` ids. `Number("abc")` on the JS side arrives as
+  /// NaN, and `Int(Double.nan)` traps; likewise `Int(1e20)` traps even though
+  /// 1e20 is finite, so the upper bound must be checked before the `Int(...)`
+  /// conversion. Bounded to `Int32.max` and requires >= 1 to match Android's
+  /// rejection of ids <= 0.
+  private func instreamId(_ adUnitIdentifier: Double,
+                          _ reject: (String, String, NSError?) -> Void) -> Int? {
+    guard adUnitIdentifier.isFinite,
+          adUnitIdentifier >= 1,
+          adUnitIdentifier <= Double(Int32.max) else {
+      reject("EzoicAds", "Invalid adUnitIdentifier: \(adUnitIdentifier)", nil)
+      return nil
+    }
+    return Int(adUnitIdentifier)
+  }
+
+  @objc public func loadInstreamAd(_ adUnitIdentifier: Double,
+                                   contentUrl: String?,
+                                   resolve: @escaping (Any?) -> Void,
+                                   reject: @escaping (String, String, NSError?) -> Void) {
+    onMain { [weak self] in
+      guard let self = self else { return }
+      guard let id = self.instreamId(adUnitIdentifier, reject) else { return }
+      // Reject overlapping loads: the native load silently no-ops while an
+      // earlier one is in flight, which would hang this promise forever.
+      if self.pendingInstreamLoads[id] != nil {
+        reject("EzoicAds", "An instream ad is already loading for ad unit \(id)", nil)
+        return
+      }
+      // Create-or-reuse: instream is multi-use, so a repeat load on the same id
+      // reuses the existing native controller (preserving its tag state).
+      let ad: EzoicInstreamAd
+      if let existing = self.instreamAds[id] {
+        ad = existing
+      } else {
+        ad = EzoicInstreamAd(adUnitId: id)
+        self.instreamAds[id] = ad
+      }
+      // Register the pending holder BEFORE calling load: early validation
+      // failures deliver the delegate callback synchronously.
+      self.pendingInstreamLoads[id] = PendingInstreamLoad(resolve: resolve, reject: reject)
+      ad.load(contentUrl: contentUrl, delegate: self)
+    }
+  }
+
+  @objc public func getInstreamNextAdTagUrl(_ adUnitIdentifier: Double,
+                                            resolve: @escaping (Any?) -> Void,
+                                            reject: @escaping (String, String, NSError?) -> Void) {
+    onMain { [weak self] in
+      guard let self = self else { return }
+      guard let id = self.instreamId(adUnitIdentifier, reject) else { return }
+      // Native getNextAdTagUrl returns nil once the waterfall is exhausted,
+      // before a successful load, or after destroy — surface that as JS null.
+      resolve(self.instreamAds[id]?.getNextAdTagUrl())
+    }
+  }
+
+  @objc public func reportInstreamImpression(_ adUnitIdentifier: Double,
+                                             revenueUsd: NSNumber?,
+                                             resolve: @escaping (Any?) -> Void,
+                                             reject: @escaping (String, String, NSError?) -> Void) {
+    onMain { [weak self] in
+      guard let self = self else { return }
+      guard let id = self.instreamId(adUnitIdentifier, reject) else { return }
+      self.instreamAds[id]?.reportImpression(revenueUsd: revenueUsd?.doubleValue)
+      resolve(nil)
+    }
+  }
+
+  @objc public func destroyInstreamAd(_ adUnitIdentifier: Double,
+                                      resolve: @escaping (Any?) -> Void,
+                                      reject: @escaping (String, String, NSError?) -> Void) {
+    onMain { [weak self] in
+      guard let self = self else { return }
+      guard let id = self.instreamId(adUnitIdentifier, reject) else { return }
+      // Native suppresses load callbacks once destroyed, so settle any pending
+      // load's promise here first or it hangs forever.
+      if let pending = self.pendingInstreamLoads.removeValue(forKey: id), !pending.settled {
+        pending.settled = true
+        pending.reject("EzoicAds", "Instream ad was destroyed while loading", nil)
+      }
+      self.instreamAds.removeValue(forKey: id)?.destroy()
+      resolve(nil)
+    }
+  }
+
+  /// Module teardown parity with Android's `EzoicAdsModule.invalidate`: settle
+  /// every pending instream load with an error and destroy every controller so
+  /// no promise hangs and no native resource leaks.
+  @objc public func invalidate() {
+    onMain { [weak self] in
+      guard let self = self else { return }
+      for (_, pending) in self.pendingInstreamLoads where !pending.settled {
+        pending.settled = true
+        pending.reject("EzoicAds", "Module was destroyed while loading", nil)
+      }
+      self.pendingInstreamLoads.removeAll()
+      for (_, ad) in self.instreamAds {
+        ad.destroy()
+      }
+      self.instreamAds.removeAll()
+    }
+  }
 }
 
 // MARK: - EzoicRewardedAdDelegate
@@ -310,3 +439,34 @@ extension EzoicAdsImpl: EzoicInterstitialAdDelegate {
     }
   }
 }
+
+// MARK: - EzoicInstreamAdDelegate
+
+extension EzoicAdsImpl: EzoicInstreamAdDelegate {
+
+  // Delegate callbacks arrive on main (see `onMain`), matching the rewarded /
+  // interstitial extensions which touch shared state directly. Removal happens
+  // only inside the not-yet-settled branch (settled-conditional removal) so a
+  // stale callback can't evict a newer load's holder after destroy→reload.
+  public func instreamAd(_ instreamAd: EzoicInstreamAd, didReceiveAdTag adTagUrl: String) {
+    let id = instreamAd.adUnitId
+    // Identity check: after destroy->reload for this id, a late callback from
+    // the destroyed controller must not settle the newer load's promise.
+    guard self.instreamAds[id] === instreamAd else { return }
+    guard let pending = pendingInstreamLoads[id], !pending.settled else { return }
+    pending.settled = true
+    pendingInstreamLoads.removeValue(forKey: id)
+    pending.resolve(adTagUrl)
+  }
+
+  public func instreamAd(_ instreamAd: EzoicInstreamAd, didFailToLoadWithError error: EzoicError) {
+    let id = instreamAd.adUnitId
+    // Identity check: after destroy->reload for this id, a late callback from
+    // the destroyed controller must not settle the newer load's promise.
+    guard self.instreamAds[id] === instreamAd else { return }
+    guard let pending = pendingInstreamLoads[id], !pending.settled else { return }
+    pending.settled = true
+    pendingInstreamLoads.removeValue(forKey: id)
+    pending.reject("EzoicAds", error.localizedDescription, error as NSError)
+  }
+}