@capacitor-community/admob 8.2.1 → 8.3.0

package/README.md

@@ -190,7 +190,7 @@ Start with [Installation](#installation) above, then [Configuration](https://doc
 - [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.
+- [Native Ads](./docs/native-ads.md) — feed placement, styling, lifecycle, and events.
 - 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.

package/android/build.gradle

@@ -53,14 +53,18 @@ android {
 }
 
 repositories {
+    if (project.hasProperty('nativeUIEngineRepository')) {
+        maven { url = uri(project.property('nativeUIEngineRepository')) }
+    }
     google()
-        mavenCentral()
+    mavenCentral()
 
 }
 
 def testRunner = "1.7.0"
 
 dependencies {
+    implementation "io.github.webview-native-ui:engine:${project.findProperty('nativeUIEngineVersion') ?: '1.0.0'}"
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
 

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

@@ -84,6 +84,11 @@ public class AdMob extends Plugin {
     @Override
     public void load() {
         super.load();
+        try {
+            io.github.webview_native_ui.engine.NativeUIProjection.install(getBridge().getWebView());
+        } catch (Exception error) {
+            android.util.Log.w(getLogTag(), "Native UI channel unavailable; retaining native tracking", error);
+        }
         if (
             androidx.webkit.WebViewFeature.isFeatureSupported(androidx.webkit.WebViewFeature.WEB_MESSAGE_LISTENER) &&
             !getBridge().getConfig().isUsingLegacyBridge()
@@ -276,6 +281,16 @@ public class AdMob extends Plugin {
         nativeAdExecutor.remove(call);
     }
 
+    @PluginMethod
+    public void captureNativeAdSnapshot(final PluginCall call) {
+        nativeAdExecutor.captureSnapshot(call);
+    }
+
+    @PluginMethod
+    public void prepareNativeAdSnapshot(final PluginCall call) {
+        nativeAdExecutor.prepareSnapshot(call);
+    }
+
     // ---------------------------------------------------------
     // INTERSTITIAL ADS
     // ---------------------------------------------------------

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

@@ -2,8 +2,19 @@ package com.getcapacitor.community.admob.nativeads
 
 import android.app.Activity
 import android.content.Context
+import io.github.webview_native_ui.engine.NativeUIProjection
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.drawable.GradientDrawable
+import android.os.Debug
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import android.util.Base64
 import android.view.View
 import android.view.ViewGroup
+import android.webkit.WebView
 import android.widget.FrameLayout
 import androidx.core.util.Supplier
 import com.getcapacitor.JSArray
@@ -23,6 +34,7 @@ import com.google.android.gms.common.util.BiConsumer
 import org.json.JSONException
 import org.json.JSONObject
 import java.util.concurrent.atomic.AtomicBoolean
+import java.io.ByteArrayOutputStream
 import kotlin.math.roundToInt
 
 class NativeAdExecutor(
@@ -39,8 +51,16 @@ class NativeAdExecutor(
         val nativeAd: NativeAd,
         val adView: NativeAdView,
         val clippingContainer: FrameLayout,
+        val opaqueBackground: Boolean,
         var generation: Int = -1,
-    )
+        var projection: NativeUIProjection? = null,
+        var projectionIdentity: JSObject? = null,
+        var projectionVisible: Boolean = true,
+        var deferredPlacement: JSONObject? = null,
+
+    ) {
+        var placementSequence: Long = -1
+    }
 
     private data class PendingLoad(
         val call: PluginCall,
@@ -51,6 +71,7 @@ class NativeAdExecutor(
     private val states = mutableMapOf<String, NativeAdState>()
     private val pendingLoads = mutableMapOf<String, PendingLoad>()
     private val feedSessions = NativeAdFeedSessions()
+    private val snapshotCapturePending = AtomicBoolean(false)
 
     fun startFeed(call: PluginCall) {
         val feedId = requiredString(call, "feedId") ?: return
@@ -142,26 +163,61 @@ class NativeAdExecutor(
         requiredString(call, "feedId") ?: return
         requiredString(call, "sessionId") ?: return
         activitySupplier.get().runOnUiThread {
-            applyPlacements(call.data)
-            call.resolve()
+            applyPlacements(call.data) { hidden ->
+                if (hidden) call.resolve() else call.reject("Native ad projection did not finish hiding")
+            }
         }
     }
 
-    private fun applyPlacements(batch: JSONObject) {
+    private fun applyPlacements(batch: JSONObject, complete: ((Boolean) -> Unit)? = null) {
         val feedId = batch.optString("feedId")
         val sessionId = batch.optString("sessionId")
-        if (!isCurrentSession(feedId, sessionId) || !feedSessions.accepts(feedId, batch.optLong("sequence", -1L))) return
+        if (!isCurrentSession(feedId, sessionId) || !feedSessions.accepts(feedId, batch.optLong("sequence", -1L))) { complete?.invoke(true); return }
+        val sequence = batch.optLong("sequence", -1L)
+        val eligible = states.filter { it.value.feedId == feedId && it.value.placementSequence < sequence }.keys.toSet()
         val shown = mutableSetOf<String>()
+        val retained = mutableSetOf<String>()
         val placements = batch.optJSONArray("placements") ?: JSArray()
         repeat(placements.length()) { index ->
             try {
-                applyPlacement(feedId, placements.getJSONObject(index))?.let { shown.add(it) }
+                val placement = placements.getJSONObject(index)
+                val key = stateKey(feedId, placement.optString("slotKey"))
+                if (key in eligible) {
+                    if (placement.optBoolean("retain", false)) {
+                        val state = states[key]
+                        if (state != null && placement.optString("feedId") == feedId &&
+                            placement.optInt("generation", -1) == state.generation && placement.optBoolean("visible", false) &&
+                            state.projectionVisible && state.clippingContainer.visibility == View.VISIBLE) {
+                            shown.add(key)
+                            retained.add(key)
+                        }
+                    } else applyPlacement(feedId, placement)?.let { shown.add(it) }
+                }
             } catch (_: JSONException) {
                 // Invalid entries fail closed below.
             }
         }
-        states.filter { it.value.feedId == feedId && it.key !in shown }.values.forEach {
+        val hiding = mutableListOf<NativeUIProjection>()
+        // Retain carries no new geometry. A delayed retain must not supersede
+        // the final position arriving independently through the Engine channel.
+        (eligible - retained).forEach { states[it]?.placementSequence = sequence }
+        states.filter { it.key in eligible && it.key !in shown }.values.forEach {
+            it.deferredPlacement = null
             it.clippingContainer.visibility = View.GONE
+            if (it.projectionVisible || complete != null) it.projection?.let(hiding::add)
+            if (it.projectionVisible) {
+                it.projectionVisible = false
+                it.projectionIdentity?.let { event -> notifyListeners("nativeAdProjectionHidden", event) }
+            }
+        }
+        if (hiding.isEmpty()) complete?.invoke(true)
+        else {
+            var remaining = hiding.size
+            var succeeded = true
+            hiding.forEach { projection -> projection.hide { result ->
+                succeeded = succeeded && result
+                if (--remaining == 0) complete?.invoke(succeeded)
+            } }
         }
     }
 
@@ -228,9 +284,65 @@ class NativeAdExecutor(
             return
         }
 
-        val state = NativeAdState(feedId, template == "small", pendingLoad.token, nativeAd, adView, clippingContainer)
+        val backgroundColor = (adView.background as? GradientDrawable)?.color?.defaultColor
+        val state = NativeAdState(
+            feedId, template == "small", pendingLoad.token, nativeAd, adView, clippingContainer,
+            backgroundColor != null && Color.alpha(backgroundColor) == 255,
+        )
         states[stateKey] = state
         overlayParent.addView(clippingContainer)
+        pendingLoad.call.getString("projectionSelector")?.let { selector ->
+            val event = identity(feedId, sessionId, slotKey).apply { put("loadId", java.util.UUID.randomUUID().toString()) }
+            state.projectionIdentity = event
+            val webView = webViewSupplier.get() as? WebView
+            if (webView != null) webView.post {
+                if (states[stateKey] !== state) return@post
+                state.projection = runCatching {
+                    NativeUIProjection(
+                        window = activitySupplier.get().window,
+                        webView = webView,
+                        plugin = "AdMob",
+                        projectionSelector = selector,
+                        receiveListeners = NativeUIProjection.ReceiveListeners(
+                            update = listOf("nativeAdProjectionUpdated"),
+                            projection = NativeUIProjection.ReceiveListeners.Projection(
+                                native = listOf("nativeAdProjectionShown"), none = listOf("nativeAdProjectionHidden")
+                            ),
+                            match = mapOf("feedId" to feedId, "sessionId" to sessionId, "slotKey" to slotKey, "loadId" to event.optString("loadId"))
+                        ),
+                        failedFallback = NativeUIProjection.FailedFallback.NATIVE,
+                        captureMode = NativeUIProjection.CaptureMode.VIEW,
+                        updatePlacement = { placement ->
+                            check(states[stateKey] === state && isCurrentSession(feedId, sessionId)) { "Native ad owner changed" }
+                            check(placement.optString("feedId") == feedId && placement.optString("sessionId") == sessionId &&
+                                placement.optString("slotKey") == slotKey) { "Native ad placement identity changed" }
+                            check(placement.optInt("generation", -1) >= state.generation &&
+                                placement.optLong("sequence", -1L) > state.placementSequence && state.projectionVisible) {
+                                "Native ad placement is stale or hidden"
+                            }
+                            if (!placement.optBoolean("visible", false)) {
+                                state.placementSequence = placement.optLong("sequence")
+                                state.deferredPlacement = null
+                                state.clippingContainer.visibility = View.GONE
+                                state.projectionVisible = false
+                                state.projection?.hide()
+                                error("Native ad placement is not visible")
+                            }
+                            check(applyPlacement(feedId, placement, defer = false) == stateKey) { "Native ad placement is invalid" }
+                            state.placementSequence = placement.optLong("sequence")
+                        },
+                        beforeNativeReveal = {
+                            val placement = state.deferredPlacement
+                            state.deferredPlacement = null
+                            if (states[stateKey] === state && placement != null) applyPlacement(feedId, placement, defer = false)
+                        },
+                        canCapture = { states[stateKey] === state && state.opaqueBackground &&
+                            nativeAd.mediaContent?.hasVideoContent() != true && isSnapshotSizeSupported(adView.width, adView.height) },
+                        view = { if (states[stateKey] === state) adView else null }
+                    )
+                }.onFailure { android.util.Log.w("AdMob", "Native ad projection unavailable; retaining native tracking", it) }.getOrNull()
+            }
+        }
         nativeAd.setOnPaidEventListener { adValue ->
             if (states[stateKey] !== state) return@setOnPaidEventListener
             val responseInfo = nativeAd.responseInfo
@@ -287,7 +399,7 @@ class NativeAdExecutor(
         }
     }
 
-    private fun applyPlacement(expectedFeedId: String, placement: JSONObject): String? {
+    private fun applyPlacement(expectedFeedId: String, placement: JSONObject, defer: Boolean = true): 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
@@ -296,6 +408,15 @@ class NativeAdExecutor(
         val minimumHeight = (if (state.isSmall) 120 else 300) * density
         if (value.rectWidth < minimumWidth.roundToInt() || value.rectHeight < minimumHeight.roundToInt()) return null
 
+        if (defer && state.projection?.isProjecting == true &&
+            state.adView.width == value.rectWidth && state.adView.height == value.rectHeight) {
+            state.deferredPlacement = JSONObject(placement.toString())
+            state.generation = value.generation
+            return stateKey(value.feedId, value.slotKey)
+        }
+        state.deferredPlacement = null
+        val resized = state.adView.width != value.rectWidth || state.adView.height != value.rectHeight
+
         if (!state.isSmall) {
             val adView = state.adView
             if (adView.isLayoutRequested || adView.measuredWidth != value.rectWidth || adView.measuredHeight != value.rectHeight) {
@@ -329,13 +450,138 @@ class NativeAdExecutor(
         state.generation = value.generation
         state.clippingContainer.visibility = View.VISIBLE
         if (!wasVisible) state.clippingContainer.bringToFront()
+        if (!state.projectionVisible) {
+            state.projection?.show()
+            state.projectionVisible = true
+            state.projectionIdentity?.let { notifyListeners("nativeAdProjectionShown", it) }
+        }
+        if (resized) state.projectionIdentity?.let { notifyListeners("nativeAdProjectionUpdated", it) }
         return stateKey(value.feedId, value.slotKey)
     }
 
     private fun overlayParent(): ViewGroup? = webViewSupplier.get()?.parent as? ViewGroup
 
+    // Scroll snapshot proxy. SDK views remain responsible for all ad interactions.
+    fun captureSnapshot(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        val slotKey = requiredString(call, "slotKey") ?: return
+        activitySupplier.get().runOnUiThread {
+            val state = states[stateKey(feedId, slotKey)]
+            if (!isCurrentSession(feedId, sessionId) || state == null) {
+                call.reject("Snapshots require an active ad")
+                return@runOnUiThread
+            }
+            if (!state.opaqueBackground) {
+                call.reject("Snapshot underlays require an opaque native ad background")
+                return@runOnUiThread
+            }
+            if (state.nativeAd.mediaContent?.hasVideoContent() == true) {
+                call.reject("Video ads retain native tracking while scrolling")
+                return@runOnUiThread
+            }
+            val view = state.adView
+            if (!view.isShown || view.isLayoutRequested || !isSnapshotSizeSupported(view.width, view.height)) {
+                call.reject("Native ad is not ready for a bounded snapshot")
+                return@runOnUiThread
+            }
+            // One bitmap/encoder per executor, including concurrent feeds.
+            if (!snapshotCapturePending.compareAndSet(false, true)) {
+                call.reject("Another native ad snapshot is being encoded")
+                return@runOnUiThread
+            }
+            val started = SystemClock.elapsedRealtimeNanos()
+            val drawCpuStart = Debug.threadCpuTimeNanos()
+            val bitmap = try {
+                Bitmap.createBitmap(view.width, view.height, Bitmap.Config.ARGB_8888)
+            } catch (error: Exception) {
+                snapshotCapturePending.set(false)
+                call.reject("Could not allocate native ad snapshot", error)
+                return@runOnUiThread
+            }
+            try {
+                view.draw(Canvas(bitmap))
+                val drawn = SystemClock.elapsedRealtimeNanos()
+                val drawCpuMs = (Debug.threadCpuTimeNanos() - drawCpuStart) / 1_000_000.0
+                // Compression must not block the UI thread when the next gesture begins.
+                Thread {
+                    try {
+                        val encodeStart = SystemClock.elapsedRealtimeNanos()
+                        val encodeCpuStart = Debug.threadCpuTimeNanos()
+                        val bytes = ByteArrayOutputStream()
+                        bitmap.compress(Bitmap.CompressFormat.PNG, 100, bytes)
+                        val dataUrl = "data:image/png;base64," + Base64.encodeToString(bytes.toByteArray(), Base64.NO_WRAP)
+                        val timings = JSObject().apply {
+                            put("drawMs", (drawn - started) / 1_000_000.0)
+                            put("drawCpuMs", drawCpuMs)
+                            put("workerWaitMs", (encodeStart - drawn) / 1_000_000.0)
+                            put("encodeMs", (SystemClock.elapsedRealtimeNanos() - encodeStart) / 1_000_000.0)
+                            put("encodeCpuMs", (Debug.threadCpuTimeNanos() - encodeCpuStart) / 1_000_000.0)
+                            put("bitmapBytes", bitmap.byteCount)
+                            put("pngBytes", bytes.size())
+                        }
+                        call.resolve(JSObject().put("dataUrl", dataUrl).put("timings", timings))
+                    } catch (error: Exception) {
+                        call.reject("Could not encode native ad snapshot", error)
+                    } finally {
+                        bitmap.recycle()
+                        snapshotCapturePending.set(false)
+                    }
+                }.start()
+            } catch (error: Exception) {
+                bitmap.recycle()
+                snapshotCapturePending.set(false)
+                call.reject("Could not draw native ad snapshot", error)
+            }
+        }
+    }
+
+    fun prepareSnapshot(call: PluginCall) {
+        val feedId = requiredString(call, "feedId") ?: return
+        val sessionId = requiredString(call, "sessionId") ?: return
+        val slotKey = requiredString(call, "slotKey") ?: return
+        activitySupplier.get().runOnUiThread {
+            val key = stateKey(feedId, slotKey)
+            val state = states[key]
+            val webView = webViewSupplier.get() as? WebView
+            if (!isCurrentSession(feedId, sessionId) || state == null ||
+                webView == null || !webView.isAttachedToWindow || !webView.isShown) {
+                call.reject("Native ad snapshot WebView is no longer visible")
+                return@runOnUiThread
+            }
+            val completed = AtomicBoolean(false)
+            val handler = Handler(Looper.getMainLooper())
+            val timeout = Runnable {
+                if (completed.compareAndSet(false, true)) call.reject("Native ad snapshot visual state timed out")
+            }
+            handler.postDelayed(timeout, 2000)
+            try {
+                webView.postVisualStateCallback(0, object : WebView.VisualStateCallback() {
+                    override fun onComplete(requestId: Long) {
+                        if (!completed.compareAndSet(false, true)) return
+                        handler.removeCallbacks(timeout)
+                        if (!isCurrentSession(feedId, sessionId) || states[key] !== state ||
+                            !webView.isAttachedToWindow || !webView.isShown) {
+                            call.reject("Native ad snapshot was invalidated")
+                            return
+                        }
+                        // Ready for the next WebView draw, not a claim that pixels have been presented.
+                        webView.invalidate()
+                        call.resolve()
+                    }
+                })
+            } catch (error: Exception) {
+                if (completed.compareAndSet(false, true)) {
+                    handler.removeCallbacks(timeout)
+                    call.reject("Could not prepare native ad snapshot", error)
+                }
+            }
+        }
+    }
+
     private fun destroyState(stateKey: String) {
         val state = states.remove(stateKey) ?: return
+        state.projection?.close()
         (state.clippingContainer.parent as? ViewGroup)?.removeView(state.clippingContainer)
         state.adView.destroy()
         state.nativeAd.destroy()
@@ -374,5 +620,7 @@ class NativeAdExecutor(
     companion object {
         const val NATIVE_TESTER_ID = "ca-app-pub-3940256099942544/2247696110"
         private const val MAX_ADS_PER_FEED = 3
+        internal fun isSnapshotSizeSupported(width: Int, height: Int): Boolean =
+            width > 0 && height > 0 && width.toLong() * height <= 2_000_000
     }
 }

package/dist/esm/native-ads/native-ad-definitions.interface.d.ts

@@ -10,5 +10,11 @@ export interface NativeAdDefinitions {
     loadNativeAd(options: NativeAdLoadOptions): Promise<void>;
     updateNativeAdPlacements(options: NativeAdPlacementBatch): Promise<void>;
     removeNativeAd(options: NativeAdCommandIdentity): Promise<void>;
+    /** Android-only snapshot; does not change native visibility. */
+    captureNativeAdSnapshot?(options: NativeAdCommandIdentity): Promise<{
+        dataUrl: string;
+    }>;
+    /** Android-only: confirm that the appended image is ready for the next WebView draw. */
+    prepareNativeAdSnapshot?(options: NativeAdCommandIdentity): Promise<void>;
     addListener(eventName: NativeAdPluginEvents, listenerFunc: (info: (NativeAdEvent | NativeAdErrorEvent | NativeAdRevenueEvent) & NativeAdFeedSession) => void): Promise<PluginListenerHandle>;
 }

package/dist/esm/native-ads/native-ad-feed.d.ts

@@ -4,12 +4,10 @@ import type { NativeAdEvent, NativeAdErrorEvent, NativeAdRevenueEvent } from './
 import type { NativeAdFeedOptions } from './native-ad-options.interface';
 import type { NativeAdPluginEvents } from './native-ad-plugin-events.enum';
 /**
- * Experimental manager for native-ad integration research.
+ * Manages native ad placement and lifecycle in a scrolling feed.
  *
  * A stable `slotKey`, rather than the element or array index, owns the native
  * ad lifecycle. Virtual-scroller compatibility has not yet been validated.
- *
- * @experimental Native overlay gesture routing is still being validated on devices.
  */
 export declare class NativeAdFeed {
     private readonly options;
@@ -65,6 +63,8 @@ export declare class NativeAdFeed {
     private removeStateAd;
     private runOperation;
     private destroyResources;
+    private reuseProjectedPlacement;
+    private measurePlacement;
     private requestPlacementUpdate;
     private flushPlacementUpdates;
     private assertActive;