feat(admob): track next-gen banner response loading

[polmiro]

Motivation

Expose server-to-server Google Mobile Ads Next-Gen banner response loading through the RevenueCat tracking API.

This PR is stacked on #4014, which provides the core banner tracking integration and callback installation.

Description

• Add callback-based AdView.loadAndTrackAdFromResponse and AdTracker.loadAndTrackBannerAdFromResponse APIs.
• Add suspending overloads that return the original Google AdLoadResult unchanged.
• Require an explicit ad unit ID so successful and failed response loads retain attribution.
• Install lifecycle and refresh tracking before loaded banners reach application code.
• Preserve application callbacks while tracking load success and failure.
• Publish and document the experimental response-loading API.

Tracking behavior

The supplied placement and ad unit ID are used for response load events and subsequent banner lifecycle events. RevenueCat tracking and callback installation happen before application callbacks or suspending results are returned.

---

Note

Low Risk
Additive experimental API on top of existing banner tracking patterns, with focused unit tests and no changes to core purchase or auth flows.

Overview
Adds server-to-server banner loading with RevenueCat tracking for Google Mobile Ads Next-Gen, matching the existing FromResponse APIs on other formats.

New public entry points are AdView.loadAndTrackAdFromResponse and AdTracker.loadAndTrackBannerAdFromResponse, each with callback and suspending overloads. Callers must pass an explicit adUnitId (and optional placement) so load success and failure events keep correct attribution when the opaque response does not expose it.

Implementation wires AdView.loadFromAdResponse through the same tracking path as request-based banner loads: TrackingAdLoadCallback for callbacks, trackAndConfigureAdLoadResult for suspend, with lifecycle and refresh wrappers installed before app code sees the loaded BannerAd. Suspending APIs return Google’s AdLoadResult unchanged.

README and api.txt document the new surface; BannerAdResponseFlowTest covers callback ordering, failure attribution, and suspending success/failure behavior.

^{Reviewed by Cursor Bugbot for commit 9a172fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (draft-banner-pr-alignment@2fb60b8). Learn more about missing BASE report.

Additional details and impacted files

@@                     Coverage Diff                      @@
##             draft-banner-pr-alignment    #4028   +/-   ##
============================================================
  Coverage                             ?   82.99%           
============================================================
  Files                                ?      437           
  Lines                                ?    17893           
  Branches                             ?     2684           
============================================================
  Hits                                 ?    14851           
  Misses                               ?     2148           
  Partials                             ?      894           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[RevenueCat-Danger-Bot]

Public API changes in feature:admob-next-gen (4 new declarations)

+ method @KotlinOnly @com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI @kotlin.jvm.JvmSynthetic public static suspend Object? loadAndTrackBannerAdFromResponse(com.revenuecat.purchas…
+ method @KotlinOnly @com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI @kotlin.jvm.JvmSynthetic public static void loadAndTrackBannerAdFromResponse(com.revenuecat.purchases.ads.even…
+ method @KotlinOnly @com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI @kotlin.jvm.JvmSynthetic public static suspend Object? loadAndTrackAdFromResponse(com.google.android.libraries…
+ method @KotlinOnly @com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI @kotlin.jvm.JvmSynthetic public static void loadAndTrackAdFromResponse(com.google.android.libraries.ads.mobile…

Generated by 🚫 Danger

[AlvaroBrey]

Minor: loadCallback is mandatory in this PR's signatures but optional in the parent PR. Unless there's something I'm missing, they should be nullable here too?

[polmiro]

The response API has a same-named suspending overload, so loadCallback is marked required to distinguish them. The regular loader has no suspending overload, so loadCallback can remain optional without requiring callers to pass loadCallback = null. I think the result fits the ergonomics for each case well. Let me know what do you think.

[AlvaroBrey]

Hmm that makes sense, hadn't noticed.

Not gonna block on this, but the typical SDK language for suspend variants is awaitXYZ when the non-suspend is XYZ ( awaitOfferings, awaitPurchase, etc). I'd argue to switch to it for three reasons:

• Same name overrides gated by a single param are brittle in that if e.g. we added a default value to loadCallback, then a caller with no loadCallback would always be the suspend
• Just consistency with the rest of the SDK
• Would allow nullability of loadCallback for fire-and-forget usecases

[polmiro]

Sounds good. I'll do it in a follow up PR and against this and the native case as well. Thanks for the heads up