[anglinb]

What it does

Adds FCM push-token reporting, so Superwall can send server-side push notifications to Android devices. It is the Android counterpart of superwall/Superwall-iOS#571.

New public API on Superwall. All of it is callable from Java. The SDK has no Firebase dependency and never requests permission itself.

fun setPushToken(token: String)                    // from FirebaseMessagingService.onNewToken, and FirebaseMessaging.getInstance().token at launch
fun optOutOfNotifications()
fun optInToNotifications()
fun handleNotificationOpen(intent: Intent)         // the tap intent (FCM-displayed notifications carry the data as extras)
fun handleNotificationOpen(data: Map<String, String>)

A new NotificationTokenManager sends a notification_token event through the SDK's normal events queue (POST /api/v1/events). It is not a new endpoint and not a user attribute.

• When it sends:

  • when the token, the permission (re-checked on every foreground), opt in/out, or the identity changes (identify and reset);
  • otherwise as a heartbeat at most once every 24 hours.

  The SDK persists a SHA-256 fingerprint of the sent state and identity, plus the time it was sent, so nothing is re-sent per session.

• Flag gating: controlled by the user_notifications static-config toggle (FeatureFlags.userNotifications). With the flag off nothing is sent, but the state is kept in app-specific storage, which survives reset(). When the flag turns on, the state is sent once.

• Opt-out is persisted per device and survives relaunch, reset() and identify. Opting out sends the token with enabled: false.

• eventTrackingBehavior == NONE: the manager reads the events queue's own behaviour (EventsQueue.trackingBehavior, now a StateFlow). Nothing is sent or marked as sent while it is NONE, and the manager refreshes once the queue allows tracking again.

• Permission: AUTHORIZED or DENIED, from POST_NOTIFICATIONS on API 33+ and areNotificationsEnabled() below that.

• deep_link: an open is only tracked. The SDK doesn't open the link, matching iOS.

Keeping the token private

Both events are a new internal PrivateSuperwallEvent, not a SuperwallEvent. So they:

• never reach SuperwallDelegate.handleSuperwallEvent or the events flow;
• can't trigger a paywall;
• aren't saved to the on-device event store that audience filters read.

They are still sent with $is_standard_event: true.

This PR also fixes two existing log sites that would have leaked the token to SuperwallDelegate.handleLog:

• A failed /events request logged the whole batch. It now logs only the event count and names.
• A cache decode failure logged the stored JSON. It now logs only the key and the exception class.

Wire contract

notification_token parameters are unprefixed camelCase, plus the SDK's standard $ keys. The device, alias and user ids are batch headers, as for every event.

{
  "channel": "fcm",
  "address": "fT3x…:APA91b…",
  "permissionStatus": "AUTHORIZED",
  "enabled": true,
  "appVersion": "2.3.4",
  "sdkVersion": "2.9.0"
}

The address is passed exactly as given: FCM tokens are case-sensitive.

notification_open is tracked only when the FCM data has an sw key. FCM data values must be strings, so sw is a JSON string:

{ "sendId": "nsend_…", "contactPointId": "cp_…" }

That is parsed from data sw = "{\"sendId\":\"nsend_…\",\"cpId\":\"cp_…\"}". contactPointId is omitted when cpId is missing.

Server side

superwall/paywall-next has an FCM channel stack:

• #4808: DB schema;
• #4822: subs-writer accepts fcm, case-preserving contact point ids;
• #4809: vault Firebase credentials;
• then the send API, the sender and the dashboard.

The feature stays dark until the user_notifications flag is on for an app.

Testing

./gradlew :superwall:testDebugUnitTest: 1709 tests, 0 failures, 0 errors, 0 skipped. ktlint 1.5.0 is clean on the changed files.

The new suites have 35 tests:

• NotificationTokenManagerTest:
  • dedup within and after 24h;
  • re-sends on token, permission, identify, reset and opt changes;
  • opt-out persistence;
  • flag-off caching, a single flush, and the flag turned off again;
  • NONE gating.
• NotificationTokenLogicTest: sw parsing, the fingerprint and the heartbeat. It also has a wire-contract test that encodes through JsonFactory and EventsRequest, using a token with uppercase letters.
• NotificationEventTrackingTest: private events are queued, but not passed to the delegate, not stored locally and never a trigger.
• NotificationTrackingBehaviorTest: NONE → ALL through the real setter, ad-consent actor, EventsQueue and manager.
• NotificationStorageTest: the real LocalStorage.reset() keeps the token and opt-out state.
• NotificationOpenIntentTest (Robolectric): intent extras.
• EventsRequestLogTest: a failed /events request never logs the token.

🤖 Generated with Claude Code

[anglinb]

📚 Docs required

What changed for customers: New public SDK API: Superwall.setPushToken, handleNotificationOpen(intent) / handleNotificationOpen(data), optOutOfNotifications and optInToNotifications, which an Android app must call to receive Superwall notifications.

Why this needs docs: net-new public SDK API (rule 2) with setup steps the app must add (FCM token callback, tap handling). Target pages: content/docs/android/sdk-reference/Superwall.mdx (https://superwall.com/docs/android/sdk-reference/Superwall), a new Android push notifications guide, and content/docs/android/changelog.mdx.

This PR is part of the FCM (Android) channel for Superwall notifications v1. To avoid duplicate docs work, the whole channel has one docs prompt, on superwall/paywall-next#4831: https://github.com/superwall/paywall-next/pull/4831#issuecomment-6512182300. That prompt already covers this PR. Run that one; do not write a separate page from this PR.

Coverage today: absent. No page in superwall/docs mentions Superwall notifications, push tokens or FCM.

Without a docs page this change also gets no changelog entry: superwall/docs publishes a daily GitHub Release that superwall.com renders at /changelog, and every entry must link to a live docs page.

_{Flagged by the docs-required skill. If this is wrong, remove the label and say why in a
reply so the skill's calibration set can be corrected.}

[maple-review-bot]

1 inline note from Maple's review. The score and summary are in the review comment above.

[maple-review-bot]

1 inline note from Maple's review. The score and summary are in the review comment above.

[maple-review-bot]

Maple review

🟢 Confidence 10/10 · safe to merge. Regression tests cover both prior defects, while notification lifecycle, wire encoding, storage persistence, and payload privacy have dedicated tests.
_{no findings · tests covered · risk high · 2/2 new units observable}

Adds private FCM token registration and notification-open reporting through the existing events queue. The clock-rollback and dropped-registration defects are fixed; no remaining merge-blocking defects were found.

• NotificationTokenManager persists opt-outs and refreshes registrations on state, identity, and permission changes.
• PrivateSuperwallEvent keeps notification payloads out of delegates and audience storage.
• enqueueAccepted reports queue acceptance before registration fingerprints are persisted.

Fixed since the last review

• ✅ F1 · shouldSend stops heartbeats after a clock correction
• ✅ F2 · update marks dropped registrations as sent

_{3f1337a · What was checked, coverage and telemetry details are on the Maple / review check. Reply "won't fix" to dismiss a finding, or mention @maple-review-bot to ask about one.}