@mpgd/adapter-capacitor 0.12.4 → 0.13.0

package/README.md

@@ -209,7 +209,7 @@ const gateway = createCapacitorPlatformGateway({ ..., providers: [notifications]
 ```
 
 <!--
-@link src/notifications-provider.ts#createCapacitorNotificationProvider Android omits advertising from remote purposes, waits for channels before register, refuses a token when channels cannot be created, ignores a dismiss, confirms an iOS schedule by content, and keeps a Doze-deferred alarm visible to cancellation.
+@link src/notifications-provider.ts#createCapacitorNotificationProvider Android declares advertising like the FCM registry and registers rendersAdvertising with the shell's renderer, waits for channels before register, refuses a token when channels cannot be created, ignores a dismiss, confirms an iOS schedule by content, and keeps a Doze-deferred alarm visible to cancellation.
 @evidence ../../docs/specs/notifications/notifications-v2-rfc.md#profile-capacitor An Android FCM notification message cannot carry the opt-out action, and a killed-app tap is only in connectionOptions.notificationResponse.
 -->
 Create it once, early in startup: it registers its native listeners when it
@@ -321,14 +321,26 @@ is created, which is how a cold-start open reaches it.
     send names the category in `apns.payload.aps.category`.
   - The action opens the `optOutRoute` of the advertising topic the push names
     in its `topic` data key; without that key it opens nothing.
-  - An Android FCM notification message cannot carry actions, so an Android
-    advertising push needs the shell to render it natively with the action,
-    which is not built yet (a follow-up after C1). Android `remote.purposes`
-    still lists `advertising` so the provider pairs with the standard FCM
-    registry, but `validateNotificationTopicCatalog` refuses a catalog that
-    maps an advertising topic to `android`: the push would arrive without the
-    opt-out action the Korean rules require (see the RFC's advertising
-    rules). The kit's starter maps its sample advertising topic to iOS only.
+  - An Android FCM notification message cannot carry actions, so the shell
+    renders Android advertising pushes itself (AR1): the backend sends them
+    as data messages, and `dev.mpgd.capacitor.AdvertisingMessagingService`
+    from `@mpgd/capacitor-game-services`, declared as the shell's messaging
+    service in place of the messaging plugin's, posts them with the action.
+    Pass `advertisingRenderer: readCapacitorAdvertisingPushRenderer`: on
+    Android, with a catalog that maps an advertising topic, the provider
+    reads it once and registers `rendersAdvertising: true` when that service
+    is installed, and it announces its registration once the read answers,
+    so an app update that adds or removes the renderer reaches the backend
+    at its first start (once a player is signed in). Under the Korean rules the backend sends Android
+    advertising only to such an installation, and
+    `validateNotificationTopicCatalog` accepts an
+    advertising topic mapped to `android` only when the deployment sets
+    `shellRendersAdvertising: true`. Both taps open the game through the
+    messaging plugin as any push does; the plugin reports the action as a
+    `tap` with `mpgd.action: advertising-opt-out` in its data, which the
+    provider reads as the opt-out action. A read that fails or takes more
+    than five seconds counts as no renderer. The manifest lines are in the
+    [Firebase setup guide](../../docs/FIREBASE_NOTIFICATIONS.md#3-android).
 - **Settings.** Neither plugin opens the notification settings, so the
   provider takes an `openSettings` opener; without one `permission.settings`
   is `false` and `openSettings` answers `unavailable`.
@@ -405,6 +417,36 @@ iOS 13.6.0. Its Android default uses a dynamic patch selector; set
 `playServicesAdsVersion = '25.4.0'` in the game-owned `variables.gradle` to
 keep release builds reproducible until the plugin adopts a newer tested SDK.
 
+Store declarations that come with AdMob:
+
+- **Advertising ID (Android).** A shell generated without AdMob removes
+  `com.google.android.gms.permission.AD_ID` from the merged manifest
+  (`tools:node="remove"`). After installing AdMob, replace that line with
+  `<uses-permission android:name="com.google.android.gms.permission.AD_ID" />`
+  and answer "yes" to the Play Console advertising ID question; a production
+  build fails while the shell installs AdMob and still removes the permission,
+  unless `mpgd.game.json` records a deliberate no-advertising-ID policy with
+  `"ads": { "admob": { "advertisingId": "removed" } }` (for example a
+  child-directed game).
+- **Application IDs.** A production build also fails when the Android
+  `com.google.android.gms.ads.APPLICATION_ID` meta-data or the iOS
+  `GADApplicationIdentifier` is missing (the SDK stops the app at launch), and
+  warns when `SKAdNetworkItems` lacks Google's `cstr6suwn9.skadnetwork`; copy
+  the current list from Google's
+  [SKAdNetwork page](https://developers.google.com/admob/ios/3p-skadnetworks).
+- **app-ads.txt.** Set `ads.admob.publisherId` (`pub-` and 16 digits) in
+  `mpgd.game.json`, or keep a game-owned `legal/app-ads.txt` for mediation
+  lines, and `mpgd legal build` serves it at the legal site's root (and
+  removes an earlier `app-ads.txt` from the output once neither source
+  exists). The file
+  must sit at the root of the domain in the store listing (Play: developer
+  website; App Store: marketing URL), so serve the legal site from that
+  domain, not a subpath.
+- **App Tracking Transparency.** The kit does no tracking and never shows the
+  ATT prompt. A game that adds tracking (IDFA, cross-app attribution) must add
+  `NSUserTrackingUsageDescription` and request ATT before it tracks, and answer
+  the App Store privacy questions accordingly.
+
 ```ts
 import { createCapacitorPlatformGateway } from '@mpgd/adapter-capacitor';
 import { createCapacitorAdMobRewardedProvider } from '@mpgd/adapter-capacitor/admob';

package/dist/notifications-provider.d.ts

@@ -12,12 +12,22 @@ export declare const capacitorAdvertisingActionTypeId = "mpgd-advertising";
 /**
 * Keys of the push data the provider reads. A send carries the topic and the
 * topic's root-relative route in them; every other string entry reaches the
-* game as the open's untrusted `data`.
+* game as the open's untrusted `data`, except the transport's keys and the
+* Android advertising renderer's `mpgd.` keys. `action` is the renderer's
+* mark on an open from its opt-out action, which the messaging plugin
+* reports as a `tap` on Android.
 */
 export declare const capacitorNotificationDataKeys: Readonly<{
   readonly topic: 'topic';
   readonly route: 'route';
+  readonly action: 'mpgd.action';
 }>;
+/**
+* How long a registration waits for the Android advertising renderer read;
+* a read that takes longer counts as no renderer, so registrations never
+* stall on it.
+*/
+export declare const capacitorAdvertisingRendererTimeoutMs = 5000;
 /** iOS keeps at most 64 pending local notifications per app. */
 export declare const capacitorIosMaxPendingLocalNotifications = 64;
 /** How long `openSettings` waits for the app to leave for the settings screen. */
@@ -60,6 +70,20 @@ export interface CreateCapacitorNotificationProviderInput {
   /** The title of the advertising opt-out action; '수신거부' when absent. */
   readonly advertisingOptOutTitle?: string;
   /**
+  * Android: whether the shell renders advertising pushes itself, with the
+  * opt-out action (`readCapacitorAdvertisingPushRenderer` over
+  * `@mpgd/capacitor-game-services`). An Android FCM notification message
+  * cannot carry actions, so the backend sends advertising to this
+  * installation only when its registration says `rendersAdvertising`, which
+  * the provider sets when this answers true. It is read once, when the
+  * provider is created, and only when the catalog maps an advertising
+  * topic to Android. A failure, or no answer within
+  * `capacitorAdvertisingRendererTimeoutMs`, reads as false and is reported;
+  * a shell whose plugin lacks the method (`UNIMPLEMENTED`) is not.
+  * Ignored on iOS, which shows the opt-out category's action itself.
+  */
+  readonly advertisingRenderer?: () => Promise<boolean>;
+  /**
   * Opens the OS notification settings for this app. Neither plugin can, so
   * the shell supplies it (for example a small native method). Without it
   * `permission.settings` is false and `openSettings` answers 'unavailable'.

package/dist/notifications-provider.js

@@ -16,12 +16,22 @@ export const capacitorAdvertisingActionTypeId = 'mpgd-advertising';
 /**
  * Keys of the push data the provider reads. A send carries the topic and the
  * topic's root-relative route in them; every other string entry reaches the
- * game as the open's untrusted `data`.
+ * game as the open's untrusted `data`, except the transport's keys and the
+ * Android advertising renderer's `mpgd.` keys. `action` is the renderer's
+ * mark on an open from its opt-out action, which the messaging plugin
+ * reports as a `tap` on Android.
  */
 export const capacitorNotificationDataKeys = Object.freeze({
     topic: 'topic',
     route: 'route',
+    action: 'mpgd.action',
 });
+/**
+ * How long a registration waits for the Android advertising renderer read;
+ * a read that takes longer counts as no renderer, so registrations never
+ * stall on it.
+ */
+export const capacitorAdvertisingRendererTimeoutMs = 5_000;
 /** iOS keeps at most 64 pending local notifications per app. */
 export const capacitorIosMaxPendingLocalNotifications = 64;
 /** How long `openSettings` waits for the app to leave for the settings screen. */
@@ -40,7 +50,7 @@ const extraKeys = Object.freeze({
     route: 'mpgdRoute',
 });
 /** Push data keys that are not the game's: the provider's own and the transport's. */
-const reservedDataKey = /^(?:topic|route|from|collapse_key|aps|fcm_options)$|^(?:google|gcm)\./u;
+const reservedDataKey = /^(?:topic|route|from|collapse_key|aps|fcm_options)$|^(?:google|gcm|mpgd)\./u;
 const eventBufferLimit = 64;
 const maxNativeId = 0x7f_ff_ff_ff;
 /**
@@ -148,6 +158,39 @@ export function createCapacitorNotificationProvider(input) {
             // Reporting must not break the native listener that failed.
         }
     };
+    // Android advertising rendering: read once, before any registration
+    // names it. Only an Android catalog with an advertising topic asks.
+    let rendersAdvertising = false;
+    const rendererAsked = platform === 'android'
+        && push !== undefined
+        && input.advertisingRenderer !== undefined
+        && mappedTopics.some((topic) => topic.purpose === 'advertising');
+    const rendererRead = rendererAsked
+        ? (async () => {
+            let timer;
+            try {
+                const read = Promise.resolve().then(() => input.advertisingRenderer?.());
+                const late = new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        // A native call that never answers would otherwise go unnoticed.
+                        reportError(new Error(`The advertising renderer read did not answer within ${capacitorAdvertisingRendererTimeoutMs} ms; `
+                            + 'registering without rendersAdvertising.'));
+                        resolve(false);
+                    }, capacitorAdvertisingRendererTimeoutMs);
+                });
+                rendersAdvertising = (await Promise.race([read, late])) === true;
+            }
+            catch (error) {
+                // A shell built before the renderer answers UNIMPLEMENTED: it has none.
+                if (error?.code !== 'UNIMPLEMENTED') {
+                    reportError(error);
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        })()
+        : Promise.resolve();
     // Events.
     const listeners = new Set();
     const buffer = [];
@@ -295,12 +338,20 @@ export function createCapacitorNotificationProvider(input) {
             // FCM tokens only: `fcm-installation` addresses are reserved, because
             // FCM HTTP v1 cannot send to a Firebase installation id and the
             // game-services sender refuses them.
-            address: { kind: 'fcm-token', value, permission },
+            address: {
+                kind: 'fcm-token',
+                value,
+                permission,
+                ...(rendersAdvertising ? { rendersAdvertising: true } : {}),
+            },
             ...(locale === undefined || locale === '' ? {} : { locale }),
             ...(timeZone === undefined || timeZone === '' ? {} : { timeZone }),
         };
     };
-    const registrationOf = async (value) => registrationWith(value, await readAppState());
+    const registrationOf = async (value) => {
+        await rendererRead;
+        return registrationWith(value, await readAppState());
+    };
     /** The declared topic a push names; the payload is untrusted. */
     const declaredTopicOf = (data) => {
         return mappedTopic(stringOf(data[capacitorNotificationDataKeys.topic]));
@@ -315,10 +366,16 @@ export function createCapacitorNotificationProvider(input) {
         const data = isRecord(notification?.data) ? notification.data : {};
         const declared = declaredTopicOf(data);
         const topicId = declared?.id;
+        // On Android the messaging plugin reports every open as a `tap`; the
+        // advertising renderer marks one from its opt-out action in the data.
+        const action = actionId === 'tap'
+            && data[capacitorNotificationDataKeys.action] === notificationAdvertisingOptOutActionId
+            ? notificationAdvertisingOptOutActionId
+            : actionId;
         // The opt-out action opens the topic's declared opt-out screen, never a
         // route from the payload.
         let route;
-        if (actionId !== notificationAdvertisingOptOutActionId) {
+        if (action !== notificationAdvertisingOptOutActionId) {
             route = safeRoute(data[capacitorNotificationDataKeys.route]);
         }
         else if (declared?.purpose === 'advertising') {
@@ -386,6 +443,7 @@ export function createCapacitorNotificationProvider(input) {
                 ? lastObserved
                 : undefined;
             const announcedNow = announced !== undefined && androidChannelsReady;
+            const announcedRendering = rendersAdvertising;
             if (announcedNow && announced !== undefined) {
                 dispatch({
                     type: 'endpoint-changed',
@@ -408,10 +466,10 @@ export function createCapacitorNotificationProvider(input) {
                 if (registration === undefined || generation !== tokenGeneration) {
                     return;
                 }
-                const permission = registration.address.kind === 'fcm-token'
-                    ? registration.address.permission
-                    : undefined;
-                if (announcedNow && permission === announced) {
+                const address = registration.address.kind === 'fcm-token' ? registration.address : undefined;
+                if (announcedNow
+                    && address?.permission === announced
+                    && (address.rendersAdvertising === true) === announcedRendering) {
                     return;
                 }
                 dispatch({ type: 'endpoint-changed', registration });
@@ -563,6 +621,48 @@ export function createCapacitorNotificationProvider(input) {
         ensureChannels().catch(reportSetupFailure);
         ensureActionTypes().catch(reportSetupFailure);
     }
+    // A shell update that adds or removes the renderer changes the
+    // registration without a new token, and Firebase announces a token only
+    // when it changes. Once the read answers, the current registration is
+    // announced; the runtime sends it only when it differs from the last one
+    // it sent, so an app update reaches the backend at its first start.
+    if (rendererAsked && configurationIssue === undefined && push !== undefined) {
+        const generation = tokenGeneration;
+        void (async () => {
+            await rendererRead;
+            let token;
+            try {
+                token = (await push.getToken()).token;
+            }
+            catch (error) {
+                // No token yet: `tokenReceived` announces the first one. A shell
+                // that cannot answer at all is reported, as `register()` does.
+                if (isConfigurationFailure(error)) {
+                    reportError(error);
+                }
+                return;
+            }
+            if (typeof token !== 'string' || token === '' || generation !== tokenGeneration) {
+                return;
+            }
+            try {
+                await ensureChannels();
+            }
+            catch (error) {
+                reportSetupFailure(error);
+                // The foreground retry publishes this token once the channels exist.
+                if (generation === tokenGeneration && !androidChannelsReady) {
+                    retainedToken = { token, generation };
+                }
+                return;
+            }
+            const registration = await registrationOf(token);
+            // A `tokenReceived` meanwhile announced its own, which is newer.
+            if (generation === tokenGeneration) {
+                dispatch({ type: 'endpoint-changed', registration });
+            }
+        })().catch(reportError);
+    }
     // Local reminder operations run one at a time: each reads the pending list
     // and decides from it, so two at once could both take the last free slot.
     let localQueue = Promise.resolve();
@@ -597,9 +697,9 @@ export function createCapacitorNotificationProvider(input) {
                 // `createFcmProviderRegistration` publishes for android and ios.
                 // `notificationRegistryMismatch` requires that list exactly; omitting
                 // `advertising` on Android makes every standard pairing
-                // `configuration-required`. An Android FCM notification message still
-                // cannot carry the opt-out action: the catalog validator refuses an
-                // advertising topic mapped to `android` until the shell renders it
+                // `configuration-required`. An Android FCM notification message
+                // cannot carry the opt-out action: the backend sends Android
+                // advertising only to a registration with `rendersAdvertising`
                 // (RFC "Provider profiles", Capacitor).
                 purposes: ['service', 'requested', 'advertising'],
                 addressing: 'device',

package/dist/notifications-renderer.d.ts

@@ -0,0 +1,16 @@
+import { type CapacitorGameServicesPlugin } from '@mpgd/capacitor-game-services';
+/** The part of `@mpgd/capacitor-game-services` the renderer read calls. */
+export type CapacitorAdvertisingPushRendererPlugin = Pick<CapacitorGameServicesPlugin, 'getAdvertisingPushRenderer'>;
+/**
+* Whether this Android shell renders advertising pushes itself, with the
+* opt-out action: the messaging service Firebase Messaging resolves is the
+* kit's renderer (`dev.mpgd.capacitor.AdvertisingMessagingService`, which
+* `mpgd target init capacitor --providers notifications` declares in a new
+* Android project). Pass it as the provider's `advertisingRenderer`, which
+* then registers `rendersAdvertising` on Android. It throws when the plugin
+* answers anything but `{ installed: boolean }`, which the provider reports;
+* a shell built with an older plugin rejects it as `UNIMPLEMENTED`, which
+* the provider reads as no renderer without reporting it. Either way the
+* provider registers without the claim.
+*/
+export declare function readCapacitorAdvertisingPushRenderer(plugin?: CapacitorAdvertisingPushRendererPlugin): Promise<boolean>;

package/dist/notifications-renderer.js

@@ -0,0 +1,23 @@
+import { CapacitorGameServices, } from '@mpgd/capacitor-game-services';
+/**
+ * Whether this Android shell renders advertising pushes itself, with the
+ * opt-out action: the messaging service Firebase Messaging resolves is the
+ * kit's renderer (`dev.mpgd.capacitor.AdvertisingMessagingService`, which
+ * `mpgd target init capacitor --providers notifications` declares in a new
+ * Android project). Pass it as the provider's `advertisingRenderer`, which
+ * then registers `rendersAdvertising` on Android. It throws when the plugin
+ * answers anything but `{ installed: boolean }`, which the provider reports;
+ * a shell built with an older plugin rejects it as `UNIMPLEMENTED`, which
+ * the provider reads as no renderer without reporting it. Either way the
+ * provider registers without the claim.
+ */
+export async function readCapacitorAdvertisingPushRenderer(plugin = CapacitorGameServices) {
+    const result = await plugin.getAdvertisingPushRenderer();
+    const installed = typeof result === 'object' && result !== null
+        ? result.installed
+        : undefined;
+    if (typeof installed !== 'boolean') {
+        throw new Error('The advertising push renderer read answered no installed flag.');
+    }
+    return installed;
+}

package/dist/notifications.d.ts

@@ -1,9 +1,10 @@
 import { type CreateCapacitorNotificationProviderInput } from './notifications-provider.js';
 import type { CapacitorNotificationServiceProvider } from './providers.js';
 export { capacitorNotificationPluginNames, loadCapacitorNotificationSdks, type CapacitorNotificationSdkRuntime, type CapacitorNotificationSdks, type LoadCapacitorNotificationSdksInput, type LocalNotificationSdk, type LocalNotificationSdkActionType, type LocalNotificationSdkEntry, type LocalNotificationSdkSchema, type NotificationSdkChannel, type NotificationSdkPermissionState, type PushSdk, type PushSdkActionEvent, type PushSdkNotification, } from './notifications-sdk.js';
-export { capacitorAdvertisingActionTypeId, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, type CapacitorNotificationAppEvents, type CapacitorNotificationChannelSettings, type CapacitorNotificationProvider, type CreateCapacitorNotificationProviderInput, } from './notifications-provider.js';
+export { capacitorAdvertisingActionTypeId, capacitorAdvertisingRendererTimeoutMs, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, type CapacitorNotificationAppEvents, type CapacitorNotificationChannelSettings, type CapacitorNotificationProvider, type CreateCapacitorNotificationProviderInput, } from './notifications-provider.js';
 export { createBridgeNotificationProvider, createNotificationProviderBridge, createNotificationServiceProvider, createNotificationSubscriptionAdapter, type CreateBridgeNotificationProviderInput, type CreateNotificationProviderBridgeInput, type CreateNotificationServiceProviderInput, type NotificationProviderBridge, } from './notifications-bridge.js';
 export { openCapacitorNotificationSettings, type CapacitorNotificationSettingsPlugin, } from './notifications-settings.js';
+export { readCapacitorAdvertisingPushRenderer, type CapacitorAdvertisingPushRendererPlugin, } from './notifications-renderer.js';
 export type { CapacitorNotificationServiceProvider, CapacitorNotificationsV2Service, } from './providers.js';
 export interface CreateCapacitorNotificationServiceProviderInput extends CreateCapacitorNotificationProviderInput {
   /** The registry id; 'capacitor-notifications' when absent. */

package/dist/notifications.js

@@ -6,9 +6,10 @@ import { createCapacitorNotificationProvider, } from './notifications-provider.j
 // optional `@capacitor-firebase/messaging` and `@capacitor/local-notifications`
 // peers; the base adapter entry loads neither.
 export { capacitorNotificationPluginNames, loadCapacitorNotificationSdks, } from './notifications-sdk.js';
-export { capacitorAdvertisingActionTypeId, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, } from './notifications-provider.js';
+export { capacitorAdvertisingActionTypeId, capacitorAdvertisingRendererTimeoutMs, capacitorIosMaxPendingLocalNotifications, capacitorLocalNotificationId, capacitorNotificationChannelId, capacitorNotificationDataKeys, capacitorNotificationProviderId, capacitorSettingsLeaveTimeoutMs, capacitorSettingsReturnTimeoutMs, createCapacitorNotificationProvider, } from './notifications-provider.js';
 export { createBridgeNotificationProvider, createNotificationProviderBridge, createNotificationServiceProvider, createNotificationSubscriptionAdapter, } from './notifications-bridge.js';
 export { openCapacitorNotificationSettings, } from './notifications-settings.js';
+export { readCapacitorAdvertisingPushRenderer, } from './notifications-renderer.js';
 /**
  * The provider and its registry entry in one call, with the same topics, for
  * `createCapacitorPlatformGateway({ providers: [...] })`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.12.4",
+  "version": "0.13.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/game-services": "0.28.0",
-    "@mpgd/bridge": "0.15.0",
-    "@mpgd/platform": "0.27.2",
-    "@mpgd/target-config": "0.23.7",
-    "@mpgd/capacitor-game-services": "0.8.3"
+    "@mpgd/bridge": "0.16.1",
+    "@mpgd/capacitor-game-services": "0.9.0",
+    "@mpgd/game-services": "0.29.0",
+    "@mpgd/platform": "0.29.0",
+    "@mpgd/target-config": "0.23.9"
   },
   "peerDependencies": {
     "@capacitor-community/admob": "^8.1.0",
@@ -74,7 +74,7 @@
     "ttsc": "0.32.1",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/game-runtime": "0.8.1"
+    "@mpgd/game-runtime": "0.8.3"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",