@mpgd/adapter-capacitor 0.6.1 → 0.7.0

package/README.md

@@ -122,10 +122,15 @@ an unverified local guest label. Re-check consent when the game resumes or
 the privacy choice changes, and expose `admob.showPrivacyOptions()` from game
 settings where required. `getCapabilities()` reports `action-required` until
 consent is ready and `temporarily-unavailable` during a show. A timed-out
-native load or presentation reports non-retryable `action-required` and
-quarantines that SDK instance to avoid overlapping shows
-while its state is unknown. Recreating the Kit provider with the same SDK does
-not clear the quarantine; restart the native app before trying again. Do not
+native load or presentation reports `action-required` and quarantines that
+SDK instance to avoid overlapping shows. A timed-out load fails before display
+and remains quarantined until that original preparation settles; it never
+opens an ad later. A display timeout returns pending even if an SDK reward was
+observed, because earning does not prove closure. The provider retains native
+terminal listeners and clears presentation uncertainty after a confirmed late
+close. Listener registration/cleanup failures remain quarantined until native
+app restart. Recreating a Kit provider with the same SDK does not clear these
+guards. Do not
 show rewarded ads through another direct SDK caller concurrently: the plugin's
 reward and dismissal events are global, not tagged with a Kit operation ID.
 
@@ -142,6 +147,20 @@ for a later signed SSV callback without replaying the ad UI; a genuinely
 skipped ad may remain pending until game-owned support or expiry policy
 settles it. Mediation and asynchronous bridge delivery have no safe universal
 250 ms reward-event cutoff.
+
+The gateway exposes `ads.provider` with protocol `mpgd.ads.v2`. Its rewarded
+preparation is `deferred`, since the operation's SSV binding must be attached to
+the fresh load. Missing placements are `configuration-required`, consent is
+`action-required`, and interstitials are explicitly unsupported by this provider.
+Native `Showed`, `Dismissed`, and `FailedToShow` events establish presentation
+facts; the original `showRewardVideoAd` Promise establishes per-call SDK
+eligibility. Global `Rewarded` events carry no invocation identity and cannot
+bind a late reward to a new show. A requested event carries
+`claimEvidence` for server proof lookup under the original idempotency key;
+this does not assert local eligibility or a grant. Pass this actual provider to
+the shared [game runtime](../../packages/game-runtime/README.md#native-presentation-and-financial-settlement)
+to coordinate execution and deadlines above all scenes. Removing SDK listeners
+and disposing a view cannot establish native closure.
 The receiver and ledger described in [AdMob SSV](../../docs/ADMOB_SSV.md)
 remain mandatory. A late SSV callback can leave the claim pending for
 reconciliation. `isTesting: true` is for SDK test ads only; [the plugin notes
@@ -149,7 +168,12 @@ that test ads do not invoke the SSV endpoint](https://github.com/capacitor-commu
 so they cannot prove a production grant.
 
 The Kit tests cover consent, per-operation binding, reward versus dismissal,
-and bridge contracts with an injected SDK. They are not evidence of a real
+and bridge contracts with an injected SDK. Seven shared presentation vectors
+run through this real provider, the installed Capacitor gateway, and the common
+runtime: consent/action, configuration, policy, deferred preparation, deadline
+with late closure, full-screen arbitration, and background ownership. This is
+presentation coverage, not complete certification of the server-ledger vector
+matrix. The fixtures are not evidence of a real
 AdMob account, live callback delivery, native device behavior, or store policy
 approval.
 

package/dist/admob.d.ts

@@ -1,4 +1,5 @@
 import { type AdMobPlugin } from '@capacitor-community/admob';
+import { type AdProvider } from '@mpgd/platform/ads';
 import type { CapacitorServiceProvider } from './providers.js';
 /** Only the AdMob subpath imports the optional native SDK. */
 export type RewardedAdMobSdk = Pick<AdMobPlugin, 'initialize' | 'requestConsentInfo' | 'showConsentForm' | 'showPrivacyOptionsForm' | 'prepareRewardVideoAd' | 'showRewardVideoAd' | 'addListener'>;
@@ -11,8 +12,11 @@ export interface CreateCapacitorAdMobRewardedProviderInput {
   readonly isTesting?: boolean;
   readonly sdk?: RewardedAdMobSdk;
   readonly showTimeoutMs?: number;
+  /** Used for native no-fill error codes; defaults to Capacitor's platform. */
+  readonly target?: 'android' | 'ios';
 }
 export interface CapacitorAdMobRewardedProvider extends CapacitorServiceProvider {
+  readonly adProvider: AdProvider;
   /** Present UMP when required. Call before the gateway advertises ad readiness. */
   requestConsent(): Promise<boolean>;
   /** Game settings should expose this when the privacy message requires it. */

package/dist/admob.js

@@ -1,6 +1,8 @@
 import { AdMob, AdmobConsentStatus, RewardAdPluginEvents, } from '@capacitor-community/admob';
+import { Capacitor } from '@capacitor/core';
 import { admobClientRewardEvidenceSchema } from '@mpgd/game-services/admob-client-reward';
 import { admobSsvMaximumBindingFieldLength, encodeAdMobSsvCustomData, } from '@mpgd/game-services/admob-ssv';
+import { adProtocol, adProtocolVersion, assertAdPresentationEvent, assertAdShowInput, assertAdShowResult, toAdAdapter, } from '@mpgd/platform/ads';
 const unitPattern = /^ca-app-pub-\d+\/\d+$/u;
 const defaultShowTimeoutMs = 180_000;
 const loadTimeoutMs = 30_000;
@@ -11,6 +13,7 @@ const maximumCustomDataBytes = 1_024;
 // Coordinate Kit providers sharing one SDK instance, even across gateways.
 const activeSdk = new WeakSet();
 const uncertainSdk = new WeakSet();
+const pendingLoadSdk = new WeakSet();
 function response(input, result) {
     return { id: input.id, ok: true, data: result };
 }
@@ -106,116 +109,245 @@ export function createCapacitorAdMobRewardedProvider(input) {
         }
         return consentTask;
     };
-    const showRewarded = async (placementId, idempotencyKey) => {
-        const adId = adUnits.get(placementId);
-        if (adId === undefined || !canRequestAds || activeSdk.has(sdk) || uncertainSdk.has(sdk)) {
-            return { status: 'unavailable', rewardGranted: false };
+    const providerId = 'admob-rewarded';
+    const nativeTarget = input.target ?? Capacitor.getPlatform();
+    const listeners = new Set();
+    const availability = (request) => {
+        if (request.format !== 'rewarded') {
+            return { state: 'unsupported', reason: 'unsupported' };
         }
-        if (idempotencyKey.trim() === ''
-            || idempotencyKey.length > admobSsvMaximumBindingFieldLength
-            || placementId.length > admobSsvMaximumBindingFieldLength) {
-            return { status: 'failed', rewardGranted: false };
+        if (!adUnits.has(request.placementId)) {
+            return {
+                state: 'configuration-required',
+                reason: 'configuration-required',
+            };
+        }
+        if (!canRequestAds || uncertainSdk.has(sdk) || pendingLoadSdk.has(sdk)) {
+            return {
+                state: 'action-required',
+                reason: 'action-required',
+            };
+        }
+        if (activeSdk.has(sdk)) {
+            return { state: 'temporarily-unavailable', reason: 'busy' };
+        }
+        return { state: 'available' };
+    };
+    const show = async (supplied) => {
+        const request = assertAdShowInput(supplied);
+        const available = availability(request);
+        const result = (state) => assertAdShowResult({
+            providerId,
+            invocationId: request.invocationId,
+            format: request.format,
+            ...state,
+        });
+        const noStart = (reason, outcome = 'failed') => result({
+            outcome,
+            presentation: 'not-started',
+            eligibility: request.format === 'rewarded' ? 'not-earned' : 'not-applicable',
+            reason,
+        });
+        if (available.state !== 'available') {
+            return noStart(available.reason ?? 'unsupported', 'unavailable');
+        }
+        if (request.idempotencyKey.length > admobSsvMaximumBindingFieldLength
+            || request.placementId.length > admobSsvMaximumBindingFieldLength) {
+            return noStart('transient-failure');
+        }
+        const adId = adUnits.get(request.placementId);
+        if (adId === undefined) {
+            return noStart('configuration-required', 'unavailable');
         }
         activeSdk.add(sdk);
-        const handles = [];
+        let sequence = 0;
+        let started = false;
+        let displayCalled = false;
+        let closed = false;
         let rewardEarned = false;
+        let loadTimedOut = false;
+        let listenerTimedOut = false;
+        let loadFailure = 'transient-failure';
         let timer;
         let loadTimer;
-        let loadTimedOut = false;
-        let nativePreflightStarted = false;
+        const handles = [];
+        const candidate = { schema: admobClientRewardEvidenceSchema, payload: { adUnitId: adId } };
+        const emit = (event) => {
+            const published = assertAdPresentationEvent({
+                ...event,
+                providerId,
+                invocationId: request.invocationId,
+                sequence: ++sequence,
+            });
+            for (const listener of [...listeners]) {
+                try {
+                    void Promise.resolve(listener(published)).catch(() => undefined);
+                }
+                catch { /* Native observation must continue. */ }
+            }
+        };
+        let cleanupTask;
+        const cleanup = () => {
+            cleanupTask ??= (async () => {
+                const settled = await Promise.allSettled(handles.map((handle) => withTimeout(Promise.resolve().then(() => handle.remove()), listenerCleanupTimeoutMs)));
+                if (settled.some((entry) => entry.status === 'rejected')) {
+                    uncertainSdk.add(sdk);
+                }
+                activeSdk.delete(sdk);
+            })();
+            return cleanupTask;
+        };
+        const earned = (reward) => {
+            // Global Rewarded events lack invocation identity. Only the original
+            // show promise can bind a late earned callback to this operation.
+            if (!displayCalled || rewardEarned || !isRewardItem(reward)) {
+                return;
+            }
+            rewardEarned = true;
+            emit({ type: 'reward-earned', evidence: candidate });
+        };
+        let finish;
+        const terminal = new Promise((resolve) => {
+            finish = resolve;
+        });
+        const close = (failed) => {
+            if (!displayCalled || closed) {
+                return;
+            }
+            closed = true;
+            uncertainSdk.delete(sdk);
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            emit(failed ? { type: 'failed', reason: 'transient-failure' } : { type: 'closed' });
+            finish(failed ? 'failed' : 'dismissed');
+            // Also runs after the caller-facing promise has already returned pending.
+            void cleanup();
+        };
         try {
             const playerId = await withTimeout(Promise.resolve().then(() => input.getPlayerId()), preflightTimeoutMs);
             if (typeof playerId !== 'string' || playerId.trim() === ''
                 || playerId.length > admobSsvMaximumBindingFieldLength) {
-                return { status: 'failed', rewardGranted: false };
+                return noStart('transient-failure');
             }
-            const customData = encodeAdMobSsvCustomData({ playerId, placementId, idempotencyKey });
+            const customData = encodeAdMobSsvCustomData({
+                playerId,
+                placementId: request.placementId,
+                idempotencyKey: request.idempotencyKey,
+            });
             if (new TextEncoder().encode(customData).byteLength > maximumCustomDataBytes) {
-                return { status: 'failed', rewardGranted: false };
+                return noStart('transient-failure');
             }
-            // This plugin resolves showRewardVideoAd on reward, but on Android a
-            // dismissal without reward leaves that promise unresolved. Observe the
-            // terminal native events separately, and hold lifecycle through close.
-            let finish;
-            const terminal = new Promise((resolve) => {
-                finish = resolve;
+            const listen = async (promise) => {
+                try {
+                    handles.push(await withTimeout(promise, preflightTimeoutMs, (handle) => handle.remove()));
+                }
+                catch (error) {
+                    listenerTimedOut = error instanceof PreflightTimeoutError;
+                    throw error;
+                }
+            };
+            await listen(sdk.addListener(RewardAdPluginEvents.Dismissed, () => queueMicrotask(() => close(false))));
+            await listen(sdk.addListener(RewardAdPluginEvents.FailedToShow, () => close(true)));
+            await listen(sdk.addListener(RewardAdPluginEvents.Showed, () => {
+                if (displayCalled && !closed && !started) {
+                    started = true;
+                    emit({ type: 'started' });
+                }
+            }));
+            await listen(sdk.addListener(RewardAdPluginEvents.FailedToLoad, (error) => {
+                if (nativeTarget === 'android' && (error.code === 3 || error.code === 9) || nativeTarget === 'ios' && error.code === 1) {
+                    loadFailure = 'no-fill';
+                }
+            }));
+            const preparation = sdk.prepareRewardVideoAd({
+                adId,
+                ...(input.isTesting === undefined ? {} : { isTesting: input.isTesting }),
+                ssv: { userId: playerId, customData },
             });
-            nativePreflightStarted = true;
-            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.Rewarded, (reward) => {
-                if (isRewardItem(reward)) {
-                    rewardEarned = true;
+            void preparation.then(() => {
+                if (loadTimedOut) {
+                    pendingLoadSdk.delete(sdk);
                 }
-            }), preflightTimeoutMs, (handle) => handle.remove()));
-            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.Dismissed, () => {
-                // Let a same-turn Rewarded event settle before reading the flag.
-                queueMicrotask(() => finish('dismissed'));
-            }), preflightTimeoutMs, (handle) => handle.remove()));
-            handles.push(await withTimeout(sdk.addListener(RewardAdPluginEvents.FailedToShow, () => {
-                finish('failed');
-            }), preflightTimeoutMs, (handle) => handle.remove()));
+            }, () => {
+                if (loadTimedOut) {
+                    pendingLoadSdk.delete(sdk);
+                }
+            });
             const loaded = await Promise.race([
-                sdk.prepareRewardVideoAd({
-                    adId,
-                    ...(input.isTesting === undefined ? {} : { isTesting: input.isTesting }),
-                    ssv: { userId: playerId, customData },
-                }),
+                preparation,
                 new Promise((_resolve, reject) => {
-                    loadTimer = setTimeout(() => {
-                        loadTimedOut = true;
-                        reject(new Error('AdMob load timed out.'));
-                    }, loadTimeoutMs);
+                    loadTimer = setTimeout(() => { loadTimedOut = true; pendingLoadSdk.add(sdk); reject(new Error('AdMob load timed out.')); }, loadTimeoutMs);
                 }),
             ]);
             if (loadTimer !== undefined) {
                 clearTimeout(loadTimer);
                 loadTimer = undefined;
             }
-            if (typeof loaded.adUnitId !== 'string' || loaded.adUnitId.length === 0) {
-                return { status: 'failed', rewardGranted: false };
-            }
-            timer = setTimeout(() => finish('timeout'), showTimeoutMs);
-            // Always observe rejection, even if a Dismissed event wins the race.
-            const showResult = sdk.showRewardVideoAd({ adId: loaded.adUnitId });
-            const onReward = (reward) => {
-                if (isRewardItem(reward)) {
-                    rewardEarned = true;
-                }
-            };
-            const onShowError = () => finish('failed');
-            void showResult.then(onReward, onShowError);
-            const outcome = await terminal;
-            if (outcome === 'timeout') {
-                // Native presentation state is unknown: do not allow another show.
-                uncertainSdk.add(sdk);
+            if (typeof loaded.adUnitId !== 'string' || !unitPattern.test(loaded.adUnitId)) {
+                return noStart('transient-failure');
             }
-            let status = 'failed';
-            if (rewardEarned) {
-                status = 'completed';
+            // At this point SSV is attached to the original operation. Lookup correlation
+            // is useful even when the caller's deadline precedes an earned SDK callback.
+            emit({ type: 'requested', claimEvidence: candidate });
+            displayCalled = true;
+            timer = setTimeout(() => { uncertainSdk.add(sdk); emit({ type: 'unknown' }); finish('timeout'); }, showTimeoutMs);
+            let showing;
+            try {
+                showing = sdk.showRewardVideoAd({ adId: loaded.adUnitId });
             }
-            else if (outcome === 'dismissed') {
-                // Mediation may deliver reward after dismissal. Only signed SSV can
-                // later distinguish a true skip from an earned reward.
-                status = 'pending';
+            catch {
+                showing = Promise.reject(new Error('AdMob show invocation failed.'));
             }
-            else if (outcome === 'timeout') {
-                status = 'pending';
+            void showing.then((reward) => earned(reward), () => {
+                // Promise rejection alone is not a native close observation.
+                if (!closed) {
+                    uncertainSdk.add(sdk);
+                    emit({ type: 'unknown' });
+                    finish('timeout');
+                }
+            });
+            const outcome = await terminal;
+            if (outcome === 'failed') {
+                if (!started && !rewardEarned) {
+                    return noStart('transient-failure');
+                }
+                return result({
+                    outcome: 'failed',
+                    presentation: 'closed',
+                    eligibility: rewardEarned ? 'eligible' : 'unknown',
+                    reason: 'transient-failure',
+                    claimEvidence: candidate,
+                    ...(rewardEarned ? { evidence: candidate } : {}),
+                });
             }
-            return {
-                status,
-                rewardGranted: false,
-                ...(status === 'completed' || status === 'pending' ? { evidence: {
-                        schema: admobClientRewardEvidenceSchema,
-                        payload: { adUnitId: adId },
-                    } } : {}),
-            };
+            const eligibility = rewardEarned ? 'eligible' : 'unknown';
+            return result({
+                outcome: outcome === 'timeout' ? 'pending' : 'shown',
+                presentation: outcome === 'timeout' ? 'unknown' : 'closed',
+                eligibility,
+                ...(outcome === 'timeout' ? { reason: 'outcome-unknown' } : {}),
+                claimEvidence: candidate,
+                ...(rewardEarned ? { evidence: candidate } : {}),
+            });
         }
-        catch (error) {
-            const uncertain = loadTimedOut
-                || (nativePreflightStarted && error instanceof PreflightTimeoutError);
-            if (uncertain) {
+        catch {
+            if (displayCalled && !closed) {
+                uncertainSdk.add(sdk);
+                emit({ type: 'unknown' });
+                return result({
+                    outcome: 'pending',
+                    presentation: 'unknown',
+                    eligibility: rewardEarned ? 'eligible' : 'unknown',
+                    reason: 'outcome-unknown',
+                    claimEvidence: candidate,
+                    ...(rewardEarned ? { evidence: candidate } : {}),
+                });
+            }
+            if (listenerTimedOut) {
                 uncertainSdk.add(sdk);
             }
-            return { status: uncertain ? 'pending' : 'failed', rewardGranted: false };
+            return noStart(loadFailure);
         }
         finally {
             if (loadTimer !== undefined) {
@@ -224,27 +356,41 @@ export function createCapacitorAdMobRewardedProvider(input) {
             if (timer !== undefined) {
                 clearTimeout(timer);
             }
-            try {
-                const removals = handles.map((handle) => {
-                    const removal = Promise.resolve().then(() => handle.remove());
-                    return withTimeout(removal, listenerCleanupTimeoutMs);
-                });
-                const settled = await Promise.allSettled(removals);
-                if (settled.some((result) => result.status === 'rejected')) {
-                    uncertainSdk.add(sdk);
-                }
-            }
-            finally {
-                activeSdk.delete(sdk);
+            // A caller deadline cannot remove the only native close observer. Keep
+            // listeners/ownership until a definitive close, and release only this SDK.
+            if (!displayCalled || closed) {
+                await cleanup();
             }
         }
     };
+    const adProvider = {
+        id: providerId,
+        protocol: adProtocol,
+        protocolVersion: adProtocolVersion,
+        rewardSignal: 'delayed',
+        getAvailability: async (request) => availability(request),
+        async preload(request) {
+            const available = availability(request);
+            return available.state === 'available'
+                ? { status: 'deferred' }
+                : { status: 'unavailable', reason: available.reason ?? 'unsupported' };
+        },
+        show,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    const legacy = toAdAdapter(adProvider);
     return {
         id: 'admob-rewarded',
+        adProvider,
         features: ['rewardedAds'],
         methods: ['ads.preload', 'ads.showRewarded'],
         async getAvailability() {
-            if (uncertainSdk.has(sdk) || !canRequestAds) {
+            if (uncertainSdk.has(sdk) || pendingLoadSdk.has(sdk) || !canRequestAds) {
                 return { rewardedAds: 'action-required' };
             }
             return { rewardedAds: activeSdk.has(sdk) ? 'temporarily-unavailable' : 'available' };
@@ -281,7 +427,10 @@ export function createCapacitorAdMobRewardedProvider(input) {
                     || typeof request.payload.idempotencyKey !== 'string') {
                     return failure(request, 'ADMOB_REQUEST_INVALID');
                 }
-                return response(request, await showRewarded(request.payload.placementId, request.payload.idempotencyKey));
+                return response(request, await legacy.showRewarded({
+                    placementId: request.payload.placementId,
+                    idempotencyKey: request.payload.idempotencyKey,
+                }));
             },
         },
     };

package/dist/index.js

@@ -44,6 +44,8 @@ function assertCredentialMutationResponse(input, field) {
 export function createCapacitorPlatformGateway(input) {
     const bridge = input.bridge ?? CapacitorGameServices;
     const providers = createCapacitorProviderRegistry(input.providers ?? []);
+    const adProvider = providers.byMethod.get('ads.showRewarded')?.adProvider
+        ?? providers.byMethod.get('ads.showInterstitial')?.adProvider;
     const lifecycle = createCapacitorAppEvents({
         target: input.target,
         ...(input.app === undefined ? {} : { app: input.app }),
@@ -199,6 +201,7 @@ export function createCapacitorPlatformGateway(input) {
             getEntitlements: () => request('commerce.getEntitlements', {}),
         },
         ads: {
+            ...(adProvider === undefined ? {} : { provider: adProvider }),
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
             showInterstitial: (payload) => request('ads.showInterstitial', payload),

package/dist/providers.d.ts

@@ -1,4 +1,5 @@
 import type { BridgeMethod, BridgeRequest, BridgeResponse } from '@mpgd/bridge';
+import type { AdProvider } from '@mpgd/platform/ads';
 import { type PlatformProviderAvailability, type PlatformProviderFeature, type ProductType } from '@mpgd/platform';
 export interface NativeBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
@@ -14,6 +15,8 @@ export interface CapacitorServiceProvider {
   readonly bridge: NativeBridge;
   readonly features: readonly PlatformProviderFeature[];
   readonly methods: readonly BridgeMethod[];
+  /** Optional native event surface. The base adapter never imports its SDK. */
+  readonly adProvider?: AdProvider;
   getAvailability(): Promise<Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>>;
 }
 export interface CapacitorProviderRegistry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Capacitor platform adapter for mpgd Android and iOS shells.",
   "license": "MIT",
   "repository": {
@@ -43,11 +43,11 @@
   ],
   "dependencies": {
     "@capacitor/app": "8.1.1",
-    "@mpgd/bridge": "0.10.0",
-    "@mpgd/platform": "0.14.0",
-    "@mpgd/target-config": "0.17.0",
-    "@mpgd/capacitor-game-services": "0.6.0",
-    "@mpgd/game-services": "0.17.1"
+    "@mpgd/bridge": "0.11.0",
+    "@mpgd/capacitor-game-services": "0.6.1",
+    "@mpgd/game-services": "0.18.0",
+    "@mpgd/platform": "0.15.0",
+    "@mpgd/target-config": "0.17.1"
   },
   "peerDependencies": {
     "@apple/app-store-server-library": "^3.1.0",
@@ -68,7 +68,8 @@
     "@capacitor/core": "8.5.2",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@mpgd/game-runtime": "0.3.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",