Native Implementation Notes

Internals that were trimmed from the web team docs. Each section names the web-team topic it belongs to.

Notifications

Notification key (FCM Notification Configuration)

Platform	How the key is applied	How it is read back
Android	Used as the notification tag; the notification id is derived from the key, so `(tag, id)` is identical for every send with that key. `tag`/`notification_id` are ignored when a key is present.	Notification extra `mobiweb.notification_key` (and the tag)
iOS	The proxy sets it as the `apns-collapse-id` (pushes); local notifications use it as the request identifier.	`userInfo["notification_key"]`

Rendering (FCM Notification Configuration)

Android: pushes and local notifications share one renderer (NotificationRenderer). Push images are downloaded on the FCM worker thread before the notification is posted.
iOS: the Notification Service Extension maps action_set to the UNNotificationCategory with the set's id.

Remote dismiss (FCM Notification Configuration)

Android: data-only FCM message. onMessageReceived checks mobiweb_op before rendering, then cancels every active notification that matches (key extra or tag; notification group; or cancelAll()).
iOS: silent background push (content-available: 1, apns-push-type: background, priority 5). didReceiveRemoteNotification removes matching delivered and pending notifications (key: userInfo.notification_key or request identifier / collapse id; group: thread identifier), then calls the completion handler.
Dismiss through the Notification Service Extension is not implemented yet, so iOS dismiss stays best-effort.

Custom sounds (FCM Notification Configuration)

Android: the repo-root sounds/ folder (.wav), or android/app/src/main/res/raw/.
iOS: the same sounds/ folder; the build copies it into the app bundle. Sounds added to the App target directly (.wav, .caf, .aiff) still work.

See Notification Sounds for the full routing and resolution rules.

Channels and action sets (Notification Channel Management, Notifications & FCM Token)

The channel registry is persisted in app storage, restored on launch, and registered as UNNotificationCategory values on iOS.
Action sets are persisted natively and re-registered at every launch. On iOS each set becomes a UNNotificationCategory with the set's id, merged with the channel categories. Registering categories replaces the whole set, so both are always registered together.
Routing a push to its channel:
- Android: NotificationRenderer reads channel_id from the payload and builds the notification with NotificationCompat.Builder(context, channelId), so it inherits the channel's sound, vibration, importance and LED color.
- iOS: only local notifications map channel_id to the pre-registered UNNotificationCategory (AppDelegate, when category is not given). Pushes don't: the Notification Service Extension maps only category and action_set, so a push needs one of those to get a category.
The iOS AppleNotification shim communicates through WKScriptMessageHandler.

Android writes shared files to the app cache and shares them with FileProvider URIs.
iOS creates temporary files with MIME-type validation and cleans them up after the share completes.

Bluetooth (Bluetooth Direct Printing, Security Notes)

Android uses Bluetooth Classic through BluetoothSocket and BLE through BluetoothGatt. Use logcat for detailed print output.
iOS needs NSBluetoothAlwaysUsageDescription in Info.plist.

Bridge security (Security Notes)

Android* bridges are injected into every frame. To origin-scope a bridge, move it to WebViewCompat.addWebMessageListener with an allowed-origin list, which is origin-scoped and frame-aware.

FCM proxy (Request Payload)

Action request URLs must have an origin listed in the project's allowed_action_origins in the fcm-proxy project config (see fcm-proxy/docs/PROJECT_MAPPINGS.md). Web teams ask the proxy operator to add theirs.

15 November 2026