feat: add Request/options inits and ad event modifiers to NativeAdvertisement

[Uhucream]

• Add progressively disclosed NativeAdvertisement initializers so callers can
  pass a custom Request and GADAdLoaderOptions when they need them, keeping the
  ad-unit-id-only initializer as the simple default.
• Deliver NativeAdDelegate events (onTap, onSwipeGesture, onWillPresent,
  onWillDismiss, onDismiss, onAdvertisementMuted) through modifiers on
  NativeAdvertisement, wired via a Coordinator on _RepresentedUINativeAdView so
  the loader stays load-only.
• Remove the custom AdLoader injection TODO from the README and document the new
  request customization and ad event callbacks.

Co-Authored-By: Claude Opus 4.8
Claude-Session: https://claude.ai/code/session_01Amm6MWc8iGzN76MgbfwrMz

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 005476d147

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Refresh coordinator callbacks on update

When the event closures change after this UIViewRepresentable has been mounted (for example a callback captures a parent value such as the current screen/ad id, or swaps to a new analytics object), SwiftUI keeps the existing coordinator rather than rebuilding it for the new struct value. Since updateUIView only reassigns nativeAd.delegate here and the coordinator stores the original closures as immutable lets, native ad events continue invoking stale handlers; update the coordinator's stored actions from the latest representable value before assigning it as the delegate.

Useful? React with 👍 / 👎.

[Copilot]

Pull request overview

This PR extends NativeAdvertisement to support caller-provided AdMob Request and GADAdLoaderOptions, and surfaces native ad interaction lifecycle events via SwiftUI-style modifiers by wiring NativeAdDelegate through a UIViewRepresentable coordinator. The README is updated to document request customization and the new event callbacks.

Changes:

• Add progressively disclosed NativeAdvertisement initializers supporting custom Request and ad loader options.
• Forward NativeAdDelegate events (tap, swipe gesture click, full-screen present/dismiss, mute) into SwiftUI modifiers via _RepresentedUINativeAdView.Coordinator.
• Update README to document request customization and ad event callbacks; remove the AdLoader injection TODO.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
Sources/AdMobUI/Components/UIViewRepresentable/_RepresentedUINativeAdView.swift	Adds callback closures + a coordinator implementing NativeAdDelegate to forward native ad events to SwiftUI.
Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisement.swift	Adds request/options initializers and event modifiers; passes callbacks into the representable.
Sources/AdMobUI/Components/AdMobNativeAd/NativeAdLoader.swift	Allows configuring the loader with a custom Request and ad loader options, and reuses the provided request for loads.
README.md	Documents request customization and the new ad event callback modifiers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementLoader.swift:35

• Configuration documents valid ranges (e.g. numberOfAdvertisements 1...5), but the initializer currently accepts any values. Invalid values can flow into MultipleAdsAdLoaderOptions.numberOfAds or concurrency/retention logic and lead to undefined SDK behavior; it’s better to fail fast with preconditions (or clamp) at initialization time.

    public init(configuration: Configuration) {
        self.configuration = configuration

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementBinder.swift:84

• When NativeAdvertisementBinder is using the caller-supplied request/options path, loadAd(with:) will call source.adLoader.load(...) on every .onAppear, even after a successful load. That can trigger repeated (billed/rate-limited) loads when the view reappears (e.g. navigation/tab switches). Consider skipping the load once a .success ad is already present.

    func loadAd(with loader: NativeAdvertisementLoader) {
        if let source {
            source.adLoader.load(source.request)

            return
        }

.github/workflows/build-and-test.yml:60

• Building for generic/platform=iOS can unexpectedly require device signing settings and diverges from the simulator destination used for tests. Unless there’s a specific reason to build the iphoneos SDK here, prefer building the same destination as tests (simulator) to avoid CI failures due to code signing/provisioning.

          xcodebuild build \
            -scheme AdMobUI \
            -destination 'generic/platform=iOS'

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (4)

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementLoader.swift:18

• NativeAdvertisementLoader is @MainActor, but shared is declared nonisolated(unsafe). Because static let initialization can occur on whatever thread first touches it, this can construct the loader off the main actor (setting up UIKit notifications/timers) and violate the class’s actor-isolation assumptions.

@MainActor
public final class NativeAdvertisementLoader: NSObject {
    public nonisolated(unsafe) static let shared: NativeAdvertisementLoader = .init(configuration: .default)

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementBinder.swift:102

• When using the caller-supplied AdLoader path, the binder never handles adLoaderDidFinishLoading(_:). If the SDK finishes without calling didReceive or didFail (the loader has a defensive noAdvertisementReceived fallback for this), the view will stay stuck in .empty indefinitely.

extension NativeAdvertisementBinder: NativeAdLoaderDelegate {
    func adLoader(_ adLoader: AdLoader, didReceive nativeAd: NativeAd) {
        self.nativeAdvertisementPhase = .success(nativeAd)
    }

    func adLoader(_ adLoader: AdLoader, didFailToReceiveAdWithError error: any Error) {
        self.nativeAdvertisementPhase = .failure(error)
    }
}

.github/workflows/build-and-test.yml:60

• This repo currently has no SwiftPM test targets (so the Build step always runs), and the destination was changed to generic/platform=iOS. Building for a generic iOS (device) destination can introduce code-signing/device-SDK related CI failures; using the Simulator destination (and/or explicitly disabling code signing) tends to be more robust for library builds.

          set -o pipefail
          xcodebuild build \
            -scheme AdMobUI \
            -destination 'generic/platform=iOS'

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisement.swift:161

• The PR description says the new modifiers are onWillAppear / onWillDisappear, but the implementation (and README) add onWillPresent / onWillDismiss (plus onImpressionRecorded). Please update the PR description to match the shipped API names so reviewers/users aren’t misled.

    /// Adds an action to perform before the ad presents a full screen view.
    /// - Parameter action: The action to perform.
    public func onWillPresent(perform action: @escaping () -> Void) -> Self {
        var view: Self = self

        view.onWillPresentAction = action

        return view
    }

    /// Adds an action to perform before the ad's full screen view is dismissed.
    /// - Parameter action: The action to perform.
    public func onWillDismiss(perform action: @escaping () -> Void) -> Self {
        var view: Self = self

        view.onWillDismissAction = action

        return view
    }

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementBinder.swift:132

• loadAd(with:) only lends/loads once per binder instance (guard !hasStartedOwnLoad / guard advertisementLoader == nil). After a terminal failure, subsequent onAppear events will never retry, even though NativeAdvertisementLoader’s finish-loading path expects callers to re-run lend(...) to retry. Consider allowing retry when the phase is .failure, while still preventing duplicate loads when a request is already in flight or has succeeded.

    func loadAd(with loader: NativeAdvertisementLoader?) {
        if let source {
            // Without this guard, every onAppear (e.g. a NavigationStack pop or TabView switch
            // bringing this view back) would call load(_:) again and send another billed
            // request, even though the first one already succeeded or is still in flight.

.github/workflows/build-and-test.yml:60

• The CI “Build” step now targets generic/platform=iOS instead of the simulator. Building for device typically requires code signing and can fail on GitHub Actions runners when no signing identity is configured. If the goal is a sign-free build check, keep the destination on iOS Simulator.

          xcodebuild build \
            -scheme AdMobUI \
            -destination 'generic/platform=iOS'

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdLoaderDelegateAdaptor.swift:28

• Initializer doesn’t call super.init(). As an NSObject subclass, this won’t compile (Swift requires super.init() before returning).

    init(
        onReceive: @escaping (_ adLoader: AdLoader, _ nativeAd: NativeAd) -> Void,
        onFailure: @escaping (_ adLoader: AdLoader, _ error: any Error) -> Void,
        onFinishLoading: @escaping (_ adLoader: AdLoader) -> Void
    ) {
        self.onReceive = onReceive
        self.onFailure = onFailure
        self.onFinishLoading = onFinishLoading
    }

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

.github/workflows/build-and-test.yml:59

• The build-only job now targets generic/platform=iOS (device). If this workflow runs on PRs without tests, CI will no longer compile the package for the iOS Simulator, which can hide simulator-only build issues (and diverges from the xcodebuild test destination below). Consider keeping the destination as iOS Simulator here as well.

            -destination 'generic/platform=iOS'

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisementBinder.swift:63

• loadAd(with:) permanently no-ops after the first call because it only checks advertisementLoader == nil. That makes a .failure phase effectively non-retryable for a view that reappears with the same identity, which contradicts the loader’s own retry strategy (it expects the caller to call lend again after terminal failure). Consider allowing retries when the current phase is .failure, while still preventing duplicate waiter registration during an in-flight request.

        // Asking again once a loader is bound would duplicate a billed request.
        guard advertisementLoader == nil else { return }

Sources/AdMobUI/Components/AdMobNativeAd/NativeAdvertisement.swift:121

• PR description mentions delivering onWillAppear / onWillDisappear callbacks, but the public API added here is onWillPresent / onWillDismiss (matching the underlying NativeAdDelegate screen presentation callbacks). Please update the PR description (or rename the API) so the documented callback names match what’s actually shipped.

    /// Adds an action to perform before the ad presents a full screen view.
    /// - Parameter action: The action to perform.
    public func onWillPresent(perform action: @escaping () -> Void) -> Self {
        var view: Self = self

        view.onWillPresentAction = action

        return view
    }

    /// Adds an action to perform before the ad's full screen view is dismissed.
    /// - Parameter action: The action to perform.
    public func onWillDismiss(perform action: @escaping () -> Void) -> Self {