@capacitor-community/admob 8.2.0 → 8.2.1

package/CapacitorCommunityAdmob.podspec

@@ -15,6 +15,6 @@ Pod::Spec.new do |s|
   s.swift_version = '5.1'
   s.static_framework = true
   s.dependency 'Capacitor'
-  s.dependency 'Google-Mobile-Ads-SDK', '13.6.0'
+  s.dependency 'Google-Mobile-Ads-SDK', '13.11.0'
   s.dependency 'GoogleUserMessagingPlatform', '~> 3.1'
 end

package/Package.swift

@@ -11,7 +11,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
-        .package(url: "https://github.com/googleads/swift-package-manager-google-mobile-ads.git", exact: "13.6.0"),
+        .package(url: "https://github.com/googleads/swift-package-manager-google-mobile-ads.git", exact: "13.11.0"),
         .package(url: "https://github.com/googleads/swift-package-manager-google-user-messaging-platform.git", .upToNextMinor(from: "3.1.0"))
     ],
     targets: [

package/README.md

@@ -56,7 +56,7 @@ Capacitor community plugin for native AdMob. This plugin wraps the Google Mobile
 
 This plugin already ships Google Mobile Ads SDK. Install the package, then add your AdMob **application** ID in AndroidManifest / Info.plist. Google's Get started guides for [Android](https://developers.google.com/admob/android/quick-start) and [iOS](https://developers.google.com/admob/ios/quick-start) explain app IDs and SKAdNetwork identifiers (Apple's ad conversion IDs); do not add a second Mobile Ads dependency.
 
-This plugin targets `@capacitor-community/admob` **v8** and Capacitor 8.5 or later (within v8). It supports iOS 15 or later and Android API 24 or later.
+This plugin targets `@capacitor-community/admob` **v8.2.0** and Capacitor 8.5 or later (within v8). It supports iOS 15 or later and Android API 24 or later.
 
 ```bash
 npm install @capacitor-community/admob
@@ -67,7 +67,7 @@ If you still use Capacitor 7, install `@capacitor-community/admob@7`.
 
 ### Google Mobile Ads SDK versions
 
-This major version pins Google Mobile Ads SDK **25.4.x** on Android and **13.6.0** on iOS (Swift Package Manager and CocoaPods). Leave those versions unless you have a specific need. Google's [Next-Gen SDK for Android](https://developers.google.com/admob/android/next-gen) waits until the next plugin major. See [Migration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) for the policy behind the pins.
+This major version pins Google Mobile Ads SDK **25.4.x** on Android and **13.11.0** on iOS (Swift Package Manager and CocoaPods). Leave those versions unless you have a specific need. Google's [Next-Gen SDK for Android](https://developers.google.com/admob/android/next-gen) waits until the next plugin major. See [Migration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) for the policy behind the pins.
 
 ### Android configuration
 
@@ -134,7 +134,7 @@ Run `pod repo update` in `ios/`, then `npx cap sync ios` again.
 
 ## First test banner
 
-After installation and platform setup, initialize the SDK, request consent, and show a Google demo banner. Use the platform banner IDs from [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing)—do not create your own ad unit for this first check.
+After installation and platform setup, request consent, initialize the SDK when ads may be requested, and show a Google demo banner. Use the platform banner IDs from [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing)—do not create your own ad unit for this first check.
 
 Call `startAdMob` from a user action or after the UI is ready (for example a button or post-navigation hook), not only at module evaluation time.
 
@@ -148,8 +148,6 @@ const bannerAdId =
     : 'ca-app-pub-3940256099942544/6300978111';
 
 async function startAdMob() {
-  await AdMob.initialize();
-
   let consentInfo = await AdMob.requestConsentInfo();
   if (consentInfo.isConsentFormAvailable && consentInfo.status === AdmobConsentStatus.REQUIRED) {
     consentInfo = await AdMob.showConsentForm();
@@ -160,6 +158,8 @@ async function startAdMob() {
     return;
   }
 
+  await AdMob.initialize();
+
   const options: BannerAdOptions = {
     adId: bannerAdId,
     adSize: BannerAdSize.ADAPTIVE_BANNER,
@@ -184,18 +184,19 @@ Expected result: when `canRequestAds` is true, a Google test banner appears at t
 
 ## Documentation
 
-Start with [Installation](#installation) above, then [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) and [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent). Run the first test banner, then use [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) for demo units and devices. Pick an ad format from the table above. The same guides are also on the [documentation site](https://docs.rdlabo.dev/projects/capacitor-admob) (English and Japanese). If you opened this README on npm, use that site for the guides — the `docs/` files live in the GitHub repository. Method signatures are in the API section below.
+Start with [Installation](#installation) above, then [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) and [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent). Run the first test banner, then use [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) for demo units and devices. Pick an ad format from the table above. The same guides are also on the [documentation site](https://docs.rdlabo.dev/projects/capacitor-admob) (English and Japanese). If you opened this README on npm, use that site for the guides — the `docs/` files are also included in the package. Method signatures are in the API section below.
 
 - [Configuration](https://docs.rdlabo.dev/projects/capacitor-admob/docs/configuration) — `AdMob.initialize` and SDK options.
 - [Consent](https://docs.rdlabo.dev/projects/capacitor-admob/docs/consent) — privacy consent and iOS tracking authorization.
 - [Testing](https://docs.rdlabo.dev/projects/capacitor-admob/docs/testing) — demo ad units, test devices, and consent testing.
 - [Banner Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/banner) — banner options, lifecycle, and events.
+- [Native Ads (Preview)](./docs/native-ads.md) — available for testing and production use. Its API may change in a minor release while in Preview.
 - Full-screen ads:
   - [Interstitial Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/interstitial) — load, show, and multiple prepared ads.
   - [Rewarded Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/rewarded) — rewarded video, rewarded interstitial, and server-side verification.
 - [App Open Ads](https://docs.rdlabo.dev/projects/capacitor-admob/docs/app-open) — load and present on foreground transitions.
 - [Ad Events](https://docs.rdlabo.dev/projects/capacitor-admob/docs/events) — shared lifecycle events, errors, and revenue data.
-- [Migration Guide](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) — historical notes when upgrading from older plugin versions.
+- [Migration Guide](https://docs.rdlabo.dev/projects/capacitor-admob/docs/migration) — upgrade steps and behavior changes in v8.2.0 and earlier versions.
 
 <!-- rdlabo-docs-omit -->
 ## Index

package/android/src/main/java/com/getcapacitor/community/admob/AdMob.java

@@ -17,6 +17,7 @@ import com.getcapacitor.community.admob.consent.AdConsentExecutor;
 import com.getcapacitor.community.admob.helpers.AuthorizationStatusEnum;
 import com.getcapacitor.community.admob.interstitial.AdInterstitialExecutor;
 import com.getcapacitor.community.admob.interstitial.InterstitialAdCallbackAndListeners;
+import com.getcapacitor.community.admob.nativeads.NativeAdExecutor;
 import com.getcapacitor.community.admob.rewarded.AdRewardExecutor;
 import com.getcapacitor.community.admob.rewardedinterstitial.AdRewardInterstitialExecutor;
 import com.google.android.gms.ads.MobileAds;
@@ -70,6 +71,39 @@ public class AdMob extends Plugin {
 
     private final AppOpenAdPlugin appOpenAdPlugin = new AppOpenAdPlugin();
 
+    private final NativeAdExecutor nativeAdExecutor = new NativeAdExecutor(
+        this::getContext,
+        this::getActivity,
+        () -> getBridge().getWebView(),
+        this::notifyListeners,
+        getLogTag()
+    );
+
+    private boolean nativeAdPlacementChannelRegistered;
+
+    @Override
+    public void load() {
+        super.load();
+        if (
+            androidx.webkit.WebViewFeature.isFeatureSupported(androidx.webkit.WebViewFeature.WEB_MESSAGE_LISTENER) &&
+            !getBridge().getConfig().isUsingLegacyBridge()
+        ) {
+            try {
+                androidx.webkit.WebViewCompat.addWebMessageListener(
+                    getBridge().getWebView(),
+                    "capacitorAdMobPlacements",
+                    getBridge().getAllowedOriginRules(),
+                    (view, message, origin, mainFrame, reply) -> {
+                        if (mainFrame) nativeAdExecutor.updateDirectPlacements(message.getData());
+                    }
+                );
+                nativeAdPlacementChannelRegistered = true;
+            } catch (RuntimeException ignored) {
+                // Placement updates retain the regular Capacitor bridge as a fallback.
+            }
+        }
+    }
+
     @PluginMethod
     public void loadAppOpen(final PluginCall call) {
         appOpenAdPlugin.loadAppOpen(getContext(), getActivity(), call, this::notifyListeners);
@@ -213,6 +247,35 @@ public class AdMob extends Plugin {
         bannerExecutor.removeBanner(call);
     }
 
+    // ---------------------------------------------------------
+    // NATIVE ADS
+    // ---------------------------------------------------------
+
+    @PluginMethod
+    public void startNativeAdFeed(final PluginCall call) {
+        nativeAdExecutor.startFeed(call);
+    }
+
+    @PluginMethod
+    public void destroyNativeAdFeed(final PluginCall call) {
+        nativeAdExecutor.destroyFeed(call);
+    }
+
+    @PluginMethod
+    public void loadNativeAd(final PluginCall call) {
+        nativeAdExecutor.load(call);
+    }
+
+    @PluginMethod
+    public void updateNativeAdPlacements(final PluginCall call) {
+        nativeAdExecutor.updatePlacements(call);
+    }
+
+    @PluginMethod
+    public void removeNativeAd(final PluginCall call) {
+        nativeAdExecutor.remove(call);
+    }
+
     // ---------------------------------------------------------
     // INTERSTITIAL ADS
     // ---------------------------------------------------------
@@ -319,4 +382,14 @@ public class AdMob extends Plugin {
             call.reject(error.toString());
         }
     }
+
+    @Override
+    protected void handleOnDestroy() {
+        if (nativeAdPlacementChannelRegistered) {
+            androidx.webkit.WebViewCompat.removeWebMessageListener(getBridge().getWebView(), "capacitorAdMobPlacements");
+            nativeAdPlacementChannelRegistered = false;
+        }
+        nativeAdExecutor.destroyAll();
+        super.handleOnDestroy();
+    }
 }

package/android/src/main/java/com/getcapacitor/community/admob/nativeads/NativeAdExecutor.kt

@@ -0,0 +1,378 @@
+package com.getcapacitor.community.admob.nativeads
+
+import android.app.Activity
+import android.content.Context
+import android.view.View
+import android.view.ViewGroup
+import android.widget.FrameLayout
+import androidx.core.util.Supplier
+import com.getcapacitor.JSArray
+import com.getcapacitor.JSObject
+import com.getcapacitor.PluginCall
+import com.getcapacitor.community.admob.helpers.RequestHelper
+import com.getcapacitor.community.admob.models.AdMobRevenueData
+import com.getcapacitor.community.admob.models.AdOptions
+import com.getcapacitor.community.admob.models.Executor
+import com.google.android.gms.ads.AdListener
+import com.google.android.gms.ads.AdLoader
+import com.google.android.gms.ads.LoadAdError
+import com.google.android.gms.ads.nativead.NativeAd
+import com.google.android.gms.ads.nativead.NativeAdOptions
+import com.google.android.gms.ads.nativead.NativeAdView
+import com.google.android.gms.common.util.BiConsumer
+import org.json.JSONException
+import org.json.JSONObject
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.math.roundToInt
+
+class NativeAdExecutor(
+    contextSupplier: Supplier<Context>,
+    activitySupplier: Supplier<Activity>,
+    private val webViewSupplier: Supplier<View>,
+    notifyListenersFunction: BiConsumer<String, JSObject>,
+    pluginLogTag: String,
+) : Executor(contextSupplier, activitySupplier, notifyListenersFunction, pluginLogTag, "NativeAdExecutor") {
+    private data class NativeAdState(
+        val feedId: String,
+        val isSmall: Boolean,
+        val loadToken: Any,
+        val nativeAd: NativeAd,
+        val adView: NativeAdView,
+        val clippingContainer: FrameLayout,
+        var generation: Int = -1,
+    )
+
+    private data class PendingLoad(
+        val call: PluginCall,
+        val feedId: String,
+        val token: Any = Any(),
+    )
+
+    private val states = mutableMapOf<String, NativeAdState>()
+    private val pendingLoads = mutableMapOf<String, PendingLoad>()
+    private val feedSessions = NativeAdFeedSessions()
+
+    fun startFeed(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        activitySupplier.get().runOnUiThread {
+            if (!feedSessions.isCurrent(feedId, sessionId)) clearFeed(feedId)
+            if (!feedSessions.start(feedId, sessionId)) {
+                call.reject("At most two native ad feeds can be active")
+                return@runOnUiThread
+            }
+            call.resolve()
+        }
+    }
+
+    fun destroyFeed(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        activitySupplier.get().runOnUiThread {
+            if (feedSessions.isCurrent(feedId, sessionId)) {
+                clearFeed(feedId)
+                feedSessions.remove(feedId)
+            }
+            call.resolve()
+        }
+    }
+
+    fun load(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        val slotKey = requiredString(call, "slotKey") ?: return
+        val options = AdOptions.getFactory().createGenericOptions(call, NATIVE_TESTER_ID)
+        val adId = if (options.isTesting) NATIVE_TESTER_ID else requiredString(call, "adId") ?: return
+        val template = call.getString("template", "medium") ?: "medium"
+        val style = call.getObject("style", JSObject()) ?: JSObject()
+        val stateKey = stateKey(feedId, slotKey)
+        val finished = AtomicBoolean(false)
+        val pendingLoad = PendingLoad(call, feedId)
+
+        activitySupplier.get().runOnUiThread {
+            if (!isCurrentSession(feedId, sessionId)) {
+                call.reject("Native ad feed session is no longer active")
+                return@runOnUiThread
+            }
+            destroyState(stateKey)
+            cancelPendingLoad(stateKey)
+            val feedAdCount = states.values.count { it.feedId == feedId } + pendingLoads.values.count { it.feedId == feedId }
+            if (feedAdCount >= MAX_ADS_PER_FEED) {
+                call.reject("At most three native ads can be active in a feed")
+                return@runOnUiThread
+            }
+            pendingLoads[stateKey] = pendingLoad
+            val adLoader = AdLoader.Builder(contextSupplier.get(), adId)
+                .forNativeAd { nativeAd ->
+                    handleLoadedAd(
+                        nativeAd = nativeAd,
+                        adId = adId,
+                        stateKey = stateKey,
+                        pendingLoad = pendingLoad,
+                        finished = finished,
+                        feedId = feedId,
+                        sessionId = sessionId,
+                        slotKey = slotKey,
+                        template = template,
+                        style = style,
+                    )
+                }
+                .withNativeAdOptions(
+                    NativeAdOptions.Builder()
+                        .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_TOP_RIGHT)
+                        .build(),
+                )
+                .withAdListener(adListener(stateKey, pendingLoad, finished, feedId, sessionId, slotKey))
+                .build()
+
+            adLoader.loadAd(RequestHelper.createRequest(options))
+        }
+    }
+
+    // WebMessageListener delivers on the UI thread; lifecycle calls still use PluginCall.
+    fun updateDirectPlacements(raw: String?) {
+        try {
+            applyPlacements(JSONObject(raw ?: return))
+        } catch (_: JSONException) {
+            // Ignore malformed messages without affecting another feed.
+        }
+    }
+
+    fun updatePlacements(call: PluginCall) {
+        requiredString(call, "feedId") ?: return
+        requiredString(call, "sessionId") ?: return
+        activitySupplier.get().runOnUiThread {
+            applyPlacements(call.data)
+            call.resolve()
+        }
+    }
+
+    private fun applyPlacements(batch: JSONObject) {
+        val feedId = batch.optString("feedId")
+        val sessionId = batch.optString("sessionId")
+        if (!isCurrentSession(feedId, sessionId) || !feedSessions.accepts(feedId, batch.optLong("sequence", -1L))) return
+        val shown = mutableSetOf<String>()
+        val placements = batch.optJSONArray("placements") ?: JSArray()
+        repeat(placements.length()) { index ->
+            try {
+                applyPlacement(feedId, placements.getJSONObject(index))?.let { shown.add(it) }
+            } catch (_: JSONException) {
+                // Invalid entries fail closed below.
+            }
+        }
+        states.filter { it.value.feedId == feedId && it.key !in shown }.values.forEach {
+            it.clippingContainer.visibility = View.GONE
+        }
+    }
+
+    fun remove(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        val slotKey = requiredString(call, "slotKey") ?: return
+        activitySupplier.get().runOnUiThread {
+            if (isCurrentSession(feedId, sessionId)) {
+                val key = stateKey(feedId, slotKey)
+                cancelPendingLoad(key)
+                destroyState(key)
+            }
+            call.resolve()
+        }
+    }
+
+    fun destroyAll() {
+        pendingLoads.keys.toList().forEach(::cancelPendingLoad)
+        states.keys.toList().forEach(::destroyState)
+        feedSessions.clear()
+    }
+
+    private fun handleLoadedAd(
+        nativeAd: NativeAd,
+        adId: String,
+        stateKey: String,
+        pendingLoad: PendingLoad,
+        finished: AtomicBoolean,
+        feedId: String,
+        sessionId: String,
+        slotKey: String,
+        template: String,
+        style: JSObject,
+    ) {
+        if (pendingLoads[stateKey] !== pendingLoad || !finished.compareAndSet(false, true)) {
+            nativeAd.destroy()
+            return
+        }
+        pendingLoads.remove(stateKey)
+        if (template == "small" && nativeAd.mediaContent?.hasVideoContent() == true) {
+            nativeAd.destroy()
+            val message = "Small native ad template does not support video ads; use Medium"
+            val event = identity(feedId, sessionId, slotKey).apply {
+                put("code", -1)
+                put("message", message)
+            }
+            notifyListeners(NativeAdPluginEvents.FAILED_TO_LOAD, event)
+            pendingLoad.call.reject(message, "-1", event)
+            return
+        }
+        val adView = PluginNativeAdView.create(contextSupplier.get(), nativeAd, template, style)
+        val clippingContainer = FrameLayout(contextSupplier.get()).apply {
+            clipChildren = true
+            clipToPadding = true
+            visibility = View.GONE
+            addView(adView)
+        }
+        val overlayParent = overlayParent()
+        if (overlayParent == null) {
+            adView.destroy()
+            nativeAd.destroy()
+            pendingLoad.call.reject("AdMob WebView parent is unavailable")
+            return
+        }
+
+        val state = NativeAdState(feedId, template == "small", pendingLoad.token, nativeAd, adView, clippingContainer)
+        states[stateKey] = state
+        overlayParent.addView(clippingContainer)
+        nativeAd.setOnPaidEventListener { adValue ->
+            if (states[stateKey] !== state) return@setOnPaidEventListener
+            val responseInfo = nativeAd.responseInfo
+            val data = AdMobRevenueData(
+                adValue,
+                adId,
+                responseInfo?.mediationAdapterClassName ?: "",
+                responseInfo?.responseId ?: "",
+            ).apply {
+                put("feedId", feedId)
+                put("slotKey", slotKey)
+                put("sessionId", sessionId)
+            }
+            notifyListeners(NativeAdPluginEvents.AD_PAID, data)
+        }
+
+        notifyListeners(NativeAdPluginEvents.LOADED, identity(feedId, sessionId, slotKey))
+        pendingLoad.call.resolve()
+    }
+
+    private fun adListener(
+        stateKey: String,
+        pendingLoad: PendingLoad,
+        finished: AtomicBoolean,
+        feedId: String,
+        sessionId: String,
+        slotKey: String,
+    ): AdListener = object : AdListener() {
+        override fun onAdFailedToLoad(error: LoadAdError) {
+            if (pendingLoads[stateKey] !== pendingLoad) return
+            pendingLoads.remove(stateKey)
+            val event = identity(feedId, sessionId, slotKey).apply {
+                put("code", error.code)
+                put("message", error.message)
+            }
+            notifyListeners(NativeAdPluginEvents.FAILED_TO_LOAD, event)
+            if (finished.compareAndSet(false, true)) {
+                pendingLoad.call.reject(error.message, error.code.toString(), event)
+            }
+        }
+
+        override fun onAdClicked() = notifyIfCurrent(NativeAdPluginEvents.CLICKED)
+
+        override fun onAdImpression() = notifyIfCurrent(NativeAdPluginEvents.IMPRESSION)
+
+        override fun onAdOpened() = notifyIfCurrent(NativeAdPluginEvents.OPENED)
+
+        override fun onAdClosed() = notifyIfCurrent(NativeAdPluginEvents.CLOSED)
+
+        private fun notifyIfCurrent(eventName: String) {
+            if (isCurrent(stateKey, pendingLoad.token)) {
+                notifyListeners(eventName, identity(feedId, sessionId, slotKey))
+            }
+        }
+    }
+
+    private fun applyPlacement(expectedFeedId: String, placement: JSONObject): String? {
+        val density = contextSupplier.get().resources.displayMetrics.density
+        val value = NativeAdPlacementValue.parse(expectedFeedId, placement, density) ?: return null
+        val state = states[stateKey(value.feedId, value.slotKey)] ?: return null
+        if (value.generation < state.generation) return null
+        val minimumWidth = (if (state.isSmall) 120 else 144) * density
+        val minimumHeight = (if (state.isSmall) 120 else 300) * density
+        if (value.rectWidth < minimumWidth.roundToInt() || value.rectHeight < minimumHeight.roundToInt()) return null
+
+        if (!state.isSmall) {
+            val adView = state.adView
+            if (adView.isLayoutRequested || adView.measuredWidth != value.rectWidth || adView.measuredHeight != value.rectHeight) {
+                adView.measure(
+                    View.MeasureSpec.makeMeasureSpec(value.rectWidth, View.MeasureSpec.EXACTLY),
+                    View.MeasureSpec.makeMeasureSpec(value.rectHeight, View.MeasureSpec.EXACTLY),
+                )
+                adView.layout(0, 0, value.rectWidth, value.rectHeight)
+            }
+            val media = adView.mediaView ?: return null
+            if (media.measuredWidth < 120 * density || media.measuredHeight < 120 * density) return null
+        }
+
+        val webView = webViewSupplier.get() ?: return null
+        val wasVisible = state.clippingContainer.visibility == View.VISIBLE
+        val clipParams = state.clippingContainer.layoutParams
+        if (clipParams.width != value.clipWidth || clipParams.height != value.clipHeight) {
+            state.clippingContainer.layoutParams = clipParams.apply {
+                width = value.clipWidth
+                height = value.clipHeight
+            }
+        }
+        state.clippingContainer.x = webView.x + value.clipX
+        state.clippingContainer.y = webView.y + value.clipY
+        val adParams = state.adView.layoutParams
+        if (adParams.width != value.rectWidth || adParams.height != value.rectHeight) {
+            state.adView.layoutParams = FrameLayout.LayoutParams(value.rectWidth, value.rectHeight)
+        }
+        state.adView.x = (value.rectX - value.clipX).toFloat()
+        state.adView.y = (value.rectY - value.clipY).toFloat()
+        state.generation = value.generation
+        state.clippingContainer.visibility = View.VISIBLE
+        if (!wasVisible) state.clippingContainer.bringToFront()
+        return stateKey(value.feedId, value.slotKey)
+    }
+
+    private fun overlayParent(): ViewGroup? = webViewSupplier.get()?.parent as? ViewGroup
+
+    private fun destroyState(stateKey: String) {
+        val state = states.remove(stateKey) ?: return
+        (state.clippingContainer.parent as? ViewGroup)?.removeView(state.clippingContainer)
+        state.adView.destroy()
+        state.nativeAd.destroy()
+    }
+
+    private fun cancelPendingLoad(stateKey: String) {
+        pendingLoads.remove(stateKey)?.call?.reject("Native ad load was cancelled")
+    }
+
+    private fun isCurrent(stateKey: String, loadToken: Any): Boolean = states[stateKey]?.loadToken === loadToken
+
+    private fun isCurrentSession(feedId: String, sessionId: String): Boolean = feedSessions.isCurrent(feedId, sessionId)
+
+    private fun clearFeed(feedId: String) {
+        pendingLoads.filterValues { it.feedId == feedId }.keys.toList().forEach(::cancelPendingLoad)
+        states.filterValues { it.feedId == feedId }.keys.toList().forEach(::destroyState)
+    }
+
+    private fun requiredString(call: PluginCall, name: String): String? {
+        val value = call.getString(name)?.trim()
+        if (value.isNullOrEmpty()) {
+            call.reject("$name must not be empty")
+            return null
+        }
+        return value
+    }
+
+    private fun stateKey(feedId: String, slotKey: String): String = "$feedId\u0000$slotKey"
+
+    private fun identity(feedId: String, sessionId: String, slotKey: String): JSObject = JSObject().apply {
+        put("feedId", feedId)
+        put("sessionId", sessionId)
+        put("slotKey", slotKey)
+    }
+
+    companion object {
+        const val NATIVE_TESTER_ID = "ca-app-pub-3940256099942544/2247696110"
+        private const val MAX_ADS_PER_FEED = 3
+    }
+}

package/android/src/main/java/com/getcapacitor/community/admob/nativeads/NativeAdFeedSessions.kt

@@ -0,0 +1,35 @@
+package com.getcapacitor.community.admob.nativeads
+
+internal class NativeAdFeedSessions {
+    private val sessions = mutableMapOf<String, String>()
+    private val placementSequences = mutableMapOf<String, Long>()
+
+    fun start(feedId: String, sessionId: String): Boolean {
+        if (feedId !in sessions && sessions.size >= MAX_FEEDS) return false
+        sessions[feedId] = sessionId
+        placementSequences[feedId] = -1
+        return true
+    }
+
+    fun isCurrent(feedId: String, sessionId: String): Boolean = sessions[feedId] == sessionId
+
+    fun accepts(feedId: String, sequence: Long): Boolean {
+        if (sequence <= placementSequences.getOrDefault(feedId, -1)) return false
+        placementSequences[feedId] = sequence
+        return true
+    }
+
+    fun remove(feedId: String) {
+        sessions.remove(feedId)
+        placementSequences.remove(feedId)
+    }
+
+    fun clear() {
+        sessions.clear()
+        placementSequences.clear()
+    }
+
+    private companion object {
+        const val MAX_FEEDS = 2
+    }
+}

package/android/src/main/java/com/getcapacitor/community/admob/nativeads/NativeAdPlacementValue.kt

@@ -0,0 +1,44 @@
+package com.getcapacitor.community.admob.nativeads
+
+import org.json.JSONObject
+import kotlin.math.roundToInt
+
+internal class NativeAdPlacementValue private constructor(
+    val feedId: String,
+    val slotKey: String,
+    val generation: Int,
+    val rectX: Int,
+    val rectY: Int,
+    val rectWidth: Int,
+    val rectHeight: Int,
+    val clipX: Int,
+    val clipY: Int,
+    val clipWidth: Int,
+    val clipHeight: Int,
+) {
+    private fun hasArea(): Boolean = rectWidth > 0 && rectHeight > 0 && clipWidth > 0 && clipHeight > 0
+
+    companion object {
+        fun parse(expectedFeedId: String, value: JSONObject, density: Float): NativeAdPlacementValue? {
+            if (!value.optBoolean("visible", false)) return null
+            val rect = value.getJSONObject("rect")
+            val clip = value.getJSONObject("clipRect")
+            val placement = NativeAdPlacementValue(
+                feedId = value.getString("feedId"),
+                slotKey = value.getString("slotKey"),
+                generation = value.optInt("generation", -1),
+                rectX = rect.pixels("x", density),
+                rectY = rect.pixels("y", density),
+                rectWidth = rect.pixels("width", density),
+                rectHeight = rect.pixels("height", density),
+                clipX = clip.pixels("x", density),
+                clipY = clip.pixels("y", density),
+                clipWidth = clip.pixels("width", density),
+                clipHeight = clip.pixels("height", density),
+            )
+            return placement.takeIf { it.feedId == expectedFeedId && it.hasArea() }
+        }
+
+        private fun JSONObject.pixels(name: String, density: Float): Int = (getDouble(name) * density).roundToInt()
+    }
+}

package/android/src/main/java/com/getcapacitor/community/admob/nativeads/NativeAdPluginEvents.kt

@@ -0,0 +1,11 @@
+package com.getcapacitor.community.admob.nativeads
+
+internal object NativeAdPluginEvents {
+    const val LOADED = "nativeAdLoaded"
+    const val FAILED_TO_LOAD = "nativeAdFailedToLoad"
+    const val CLICKED = "nativeAdClicked"
+    const val IMPRESSION = "nativeAdImpression"
+    const val OPENED = "nativeAdOpened"
+    const val CLOSED = "nativeAdClosed"
+    const val AD_PAID = "nativeAdPaid"
+}