@usergist/feedback-react-native 0.1.2 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -1,11 +1,18 @@
 # Changelog
 
-## 0.1.2
+## 0.2.0-beta.1
 
-- Add `presentationPaused`, `pausePresentation()`, and `resumePresentation()` so analytics starts at launch while campaign UI waits for the loaded screen.
-- Drop queued UI after consent withdrawal, reset, or a changed user; recheck readiness after asynchronous survey preparation.
-- Preserve the stable native package setup. Expo remains on its separate prerelease channel.
+- Add startup presentation readiness: initialize with `presentationPaused`, then call `resumePresentation()` after the loaded screen is ready.
+- Keep analytics and networking running while campaign UI is paused; `pausePresentation()` can protect later host flows without dismissing active UI.
+- Invalidate queued presentation work after consent revocation, reset, or identity changes, including requests prepared asynchronously.
 
+## 0.2.0-beta.0
+
+- Add Expo config plugin, iOS extension/EAS setup, and an optional notification adapter.
+- Preserve existing Expo notification ownership and shared provider tokens.
+- Add scoped native delivery-receipt retries, Expo onboarding, demo and consumer checks.
+- Keep logout and consent changes from accepting stale request responses or disabling a newer push session.
+- Expo support remains prerelease until signed-device acceptance is complete.
 
 All notable changes to `@usergist/feedback-react-native` are documented here.
 Releases use [Semantic Versioning](https://semver.org/).

package/EXPO-ACCEPTANCE.md

@@ -0,0 +1,57 @@
+# Expo release evidence
+
+Status: implementation under validation; stable release is blocked.
+
+Record the exact npm archive SHA256, source commit, Expo/React Native versions,
+build profile, and app identifiers alongside each result. Never record tokens
+or provider private keys. A mocked provider or generated Firebase fixture does
+not count as a live push test.
+
+## Automated gates
+
+- Packed archive resolves every existing export, `/expo`, the Node config
+  plugin, Expo subscriber, Kotlin dispatcher, and notification extension files.
+- Expo 56.0.21 and 57.0.20: automatic and expo-notifications mode, iOS and
+  Android, with the New Architecture and repeated non-destructive prebuild.
+- Existing React Native typecheck, unit tests, codegen/package check, and builds.
+- Dashboard/API validation, Expo platform mapping, AI snippets, and onboarding.
+
+## Signed-device gates (pending)
+
+- Physical iPhone and Android: anonymous startup, identify, logout/account switch,
+  offline relaunch and eventual synchronization; no cross-user data or token binding.
+- All reference demo feedback types, surveys, in-app messages, request board,
+  comments/votes/follows, targeting, branding, and analytics.
+- UserGist push: foreground/background/terminated launch; token refresh, permission
+  denial and later recovery, channels, badge behavior, images, actions, JSON actions,
+  deep links, silent reachability and delivered/open evidence.
+- Coexistence: interleave unrelated Expo and UserGist messages, including cold
+  starts; one presentation and handler invocation per event/action. Disable
+  UserGist and verify unrelated notifications still arrive.
+- Turn off networking while a native receipt is recorded; restore it and verify
+  the original delivery timestamp is acknowledged once. Logout before retry and
+  verify that old work is never attributed to the new account.
+- iOS development APNs signing and a distribution-signed build, including
+  extension embedding, provisioning, App Group persistence and rich delivery.
+
+## Promotion
+
+Publish a prerelease with npm tag `next` for consumer acceptance after package
+and native build gates pass. Keep stable `latest` unchanged until all signed
+device gates above have evidence. Do not describe Expo support as production
+validated while this document remains pending.
+
+The public release workflow enforces this through
+`tools/expo/check-release-evidence.mjs`. Supply the repository variable
+`USERGIST_EXPO_RELEASE_EVIDENCE` as JSON with `version`, `archiveSha256`,
+`sourceCommit`, `nativeBuildRunId`, and arrays `nativeBuilds`, `regressions`, `physicalDevices`.
+Each entry has `name`, `passed: true`, and a durable HTTPS `evidenceUrl` to
+the corresponding build or device report. The script lists the exact required
+names. Prereleases require package, prebuild, ordinary React Native regression,
+and all eight Expo native combinations; stable additionally requires signed
+physical-device evidence. A missing variable blocks publication. CI builds one archive and passes that file
+to every consumer; the publish job downloads it from `nativeBuildRunId` instead
+of rebuilding it. The release tag must point to that run’s source commit.
+
+For stable promotion, validate the final stable archive too: changing a
+prerelease version changes the package bytes and invalidates its earlier hash.

package/EXPO.md

@@ -0,0 +1,103 @@
+# Expo integration (0.2 prerelease)
+
+Expo uses the same `UserGist`, `Push`, and `UserGistProvider` as React Native.
+The supported build targets are Expo 56 and 57 on iOS and Android, with the New
+Architecture enabled. Use a development client or production binary. Expo Go
+cannot provide the native bridge or durable secure storage. Browser targets
+use `@usergist/feedback-web` separately.
+
+## Base setup
+
+```sh
+npx expo install @usergist/feedback-react-native \
+  @react-native-async-storage/async-storage react-native-safe-area-context
+```
+
+Add `"@usergist/feedback-react-native"` to `expo.plugins` in app.json or
+app.config.js. Mount `UserGistProvider` once around the existing application:
+in Expo Router's `app/_layout.tsx` wrap `Slot`/`Stack`; otherwise wrap App's
+existing navigation. Call `initAsync` once with the public write key.
+
+Anonymous users work without login. For identified users, obtain a scoped
+subject token from your authenticated backend and call `identifyAsync`.
+Never put a server API token in an `EXPO_PUBLIC_` variable. Connect `setConsent`
+to the host's consent decisions, and await `reset()` before changing accounts.
+The consent screen in our demo is a test harness, not a customer requirement.
+
+## Push configuration
+
+```js
+plugins: [
+  ['@usergist/feedback-react-native', {
+    push: {
+      mode: 'automatic',
+      ios: { apsEnvironment: 'development' },
+      // android: { notificationIcon: './assets/notification-icon.png',
+      //            notificationColor: '#3366FF' },
+    },
+  }],
+]
+```
+
+Set `ios.bundleIdentifier`, `android.package`, and `android.googleServicesFile`.
+The Google JSON is Firebase's client configuration for that package ID, not
+a service-account private key. Upload APNs/FCM sending credentials to UserGist.
+Never include the .p8 or service-account key in an Expo config or application.
+
+`apsEnvironment` must match signing: development provisioning uses
+`development`; TestFlight/App Store uses `production`. This is independent of
+the UserGist data environment. Runtime registration reads this plugin setting;
+call `enablePush()` without an environment override to use it.
+
+The plugin generates the notification service extension and App Group needed
+for rich media and native iOS delivery receipts. Defaults are
+`UserGistNotificationServiceExtension`, `<bundleId>.UserGistNotificationServiceExtension`,
+and `group.<bundleId>.usergist`. Override these with `extensionTargetName`,
+`extensionBundleIdentifier`, and `appGroupIdentifier` under `push.ios`.
+EAS receives the extension metadata before provisioning. Verify the app and
+extension profiles include the same App Group.
+
+Omitting `push` keeps notification acquisition disabled. Initialization and
+configuration never request permission. After the user opts in and consent
+synchronizes, call `enablePush` from a user action. Check `result.granted` and
+`result.error`; `native_module_unavailable` or `push_not_configured` describes
+build configuration, not an OS denial. Restore opt-in only after checking
+current OS permission. `disablePush()` disables UserGist without removing an
+Expo app's shared APNs/FCM registration.
+
+## Existing expo-notifications
+
+Keep its existing plugin and handlers; place its plugin before UserGist's and
+select `push.mode: 'expo-notifications'`. Configure the adapter before init:
+
+```ts
+import * as Notifications from 'expo-notifications'
+import { configureExpoNotifications } from '@usergist/feedback-react-native/expo'
+const dispose = configureExpoNotifications(Notifications)
+```
+
+Call once in the app bootstrap, not on every screen mount. Cleanup removes
+the adapter listeners without modifying host notification handlers. The helper
+does not request permissions, grant consent, or register a user on import.
+UserGist uses native device tokens from `getDevicePushTokenAsync`, never
+ExpoPushToken values. The Android dispatcher routes UserGist payloads to our
+native renderer and other messages to Expo. On iOS, Expo retains foreground
+presentation policy and response handling. Your existing Router/deep-link
+handlers remain responsible for navigation.
+
+## Rebuilds and conflicts
+
+Native/plugin changes require rebuilding with `npx expo run:ios`,
+`npx expo run:android`, or EAS Build. EAS Update cannot add a native module.
+For manually running prebuild against existing directories, Expo 57 requires
+`--no-clean` to preserve those directories; Expo 56 preserves them by default.
+
+The plugin does not overwrite a foreign extension target or custom FCM service.
+If one exists, preserve it and integrate the existing host-forwarded `Push`
+API and extension base class following the React Native README. Do not enable
+two FCM services. Automatic composition is supported for expo-notifications;
+other SDKs require an explicit integration. Change ownership modes in a fresh
+native fixture, or review the existing host configuration before migrating.
+
+Use the Expo demo and `EXPO-ACCEPTANCE.md` for acceptance. Building or receiving
+a JavaScript callback alone is not physical-device push validation.

package/README.md

@@ -2,8 +2,41 @@
 
 Production userGist SDK for React Native and the behavioral reference for the
 iOS, Android, and Flutter packages. Use the dashboard's SDK setup flow to
-verify authentication and ingestion; push releases additionally require APNs
-or FCM configuration and physical-device validation.
+verify authentication and ingestion. The userGist APNs and FCM paths have
+passed end-to-end physical-device validation; each host app still needs its own
+provider credentials, identifiers, native callback setup, and signed-device
+acceptance test.
+
+## Expo
+
+Expo 56/57 development and production build integration is being validated for
+0.2. Use the same package with its config plugin; see [EXPO.md](EXPO.md).
+Expo Go cannot load the native bridge. See [release gates](EXPO-ACCEPTANCE.md).
+
+## Startup presentation readiness
+
+Initialize with `presentationPaused` enabled at app launch. Analytics, consent,
+identity, and networking continue while campaign UI waits. After the existing
+startup loading and navigation have finished and the loaded screen is visible,
+call `resumePresentation()`. Mount any required UserGist UI provider before that
+callback. Readiness must work for both anonymous and identified users.
+
+Call `pausePresentation()` before another flow that must not be interrupted.
+Pausing does not dismiss an already visible SDK surface. Queued feedback,
+surveys, and in-app messages are discarded if their consent is withdrawn or
+the user changes, even if consent is granted again before resuming. Repeated
+initialization keeps the first readiness setting; repeated resume calls do not
+show the same queued work twice. The option defaults to false for existing
+integrations, so upgrading alone does not enable startup deferral.
+
+Do not resume from a splash screen, an app-root mount that still shows loading,
+a disappearing screen, or a fixed timer. Use the host's existing completion
+callback; the SDK cannot infer when arbitrary startup navigation has finished.
+
+```ts
+// In the loaded screen’s existing startup/navigation completion callback:
+UserGist.resumePresentation()
+```
 
 ## Install
 
@@ -65,6 +98,7 @@ AppRegistry.registerComponent('app', () => App)
 | `UserGist.init(config)` | Returns synchronously, then hydrates and establishes the anonymous session in the background. |
 | `await UserGist.initAsync(config, initialIdentity?)` | Hydrates and optionally binds a server-proven identity before lifecycle events begin; returns `synced`, `queued`, or `rejected`. |
 | `UserGist.identify(userId, props?, subjectToken)` | Links the anonymous installation using a customer-backend-minted subject token. |
+| `await UserGist.setUserProperties(values, unsetKeys?)` | Saves flat properties for the current anonymous or identified user; returns `synced`, `queued`, or `rejected`. Requires analytics consent. |
 | `await UserGist.identifyAsync(userId, props?, subjectToken)` | Backward-compatible async identity API returning `synced`, `queued`, or `rejected`. |
 | `UserGist.track(name, props?)` | Enqueues a stable event id and immediately evaluates only server-authorized client-side campaigns; all other decisions remain server-authoritative. |
 | `await UserGist.setConsent({ analytics?, feedback?, push?, survey? })` | Persists and synchronizes the transition, refreshes targeting rules, then resolves with `true`; returns `false` when synchronization fails. |
@@ -102,6 +136,39 @@ UserGist.init(config)
 The adapter uses the same asynchronous string interface as AsyncStorage, so it
 can wrap the host application's Keychain/Keystore-backed storage.
 
+## Personalization and immediate engagement
+
+Use `await UserGist.setUserProperties({ first_name: 'Ava', country: 'IL' })` for
+current profile values and `UserGist.track('show_watched', { show_id: '00123',
+show_title: 'Midnight Orbit', position_seconds: 1234 })` for activity. Unset a
+property with `await UserGist.setUserProperties({}, ['first_name'])`. Sensitive
+fields follow the app's privacy allow-list. Both anonymous and identified users
+are supported; await reset before switching accounts.
+
+The dashboard's field picker can use a saved property, one latest matching event,
+or the triggering event. Reuse one activity source for related title/ID/position
+fields. Whole-value JSON tokens preserve types; your JSON action handler owns
+navigation. See the [personalization guide](../../apps/landing/src/app/docs/(content)/guides/personalize-messages/page.mdx)
+for authoring, fallbacks, recipient preview and a complete movie example.
+
+With the matching API release, known server-dependent engagement events flush
+immediately and can receive authorized content in the ingest response. Cached
+native feedback/in-app matching remains local. Selecting web plus mobile retains
+server consent/frequency checks while avoiding deliberate batch and polling waits.
+
+Coordinated surveys can carry a prepared attempt. Eligible repeatable, uncapped,
+non-personalized surveys can start from a signed cached permission valid for ten
+minutes; already-started sessions can upload for seven days. The SDK saves the
+original content and answers before background synchronization. Persistent storage
+is required for recovery after termination; completion retains its submission/retry
+handling. With a custom `onInvite` handler, `openSurvey(surveyId)` retains the
+invitation's authorized questions and triggering-event values. An invitation does
+not start a session until opened; failed starts retry the same attempt ID. Pending
+invitations are identity-bound and expire with the instruction (at most 24 hours);
+reset or survey-consent withdrawal clears them. On-demand/link resume remains
+available. New personalized surveys still need online resolution. See the
+[delivery and rollout notes](../../infra/docs/immediate-engagement.md).
+
 ## Architecture
 
 The SDK is a singleton that orchestrates:
@@ -230,12 +297,3 @@ silent-ping cycle for this user (saves provider quota + battery).
 ## License
 
 MIT
-
-## Startup readiness
-
-Initialize with `presentationPaused: true`. Keep `UserGistProvider` mounted, then
-call `UserGist.resumePresentation()` from the host's existing completion callback
-after startup loading and navigation finish. Do not resume from a splash screen,
-a root mount while loading, or a timer. Both anonymous and identified users work.
-`pausePresentation()` protects later host flows without dismissing active UI or
-stopping analytics. Revoked consent and user changes invalidate queued messages.

package/UserGistFeedback.podspec

@@ -23,7 +23,10 @@ Pod::Spec.new do |s|
   # The RN bridge module: RCTBridgeModule, RCTEventEmitter, Swift impl.
   # Pulls in React-Core because it imports <React/...> headers.
   s.subspec 'Core' do |core|
-    core.source_files = 'ios/*.{h,m,mm,swift}'
+    core.source_files = 'ios/*.{h,m,mm,swift}', 'ios/Shared/*.swift'
+    # This shim is internal to the Obj-C implementation. Exporting its React
+    # imports through our Swift umbrella can hide React types in host modules.
+    core.private_header_files = 'ios/UserGistPush.h'
     core.frameworks   = 'UIKit', 'UserNotifications', 'Security'
     core.dependency 'React-Core'
   end

package/UserGistFeedbackExtension.podspec

@@ -18,6 +18,6 @@ Pod::Spec.new do |s|
   s.source           = { :git => 'https://github.com/Future-Picnic/usergist-js.git', :tag => "v#{s.version}" }
   s.requires_arc     = true
   s.swift_version    = '5.7'
-  s.source_files     = 'ios/Extension/*.swift'
+  s.source_files     = 'ios/Extension/*.swift', 'ios/Shared/*.swift'
   s.frameworks       = 'UserNotifications'
 end

package/android/build.gradle

@@ -85,7 +85,9 @@ dependencies {
   // plugin in their app/build.gradle (Google's hard requirement for FCM).
   // Use a floor version that's broadly compatible with current Firebase BoM
   // ranges; consumer's BoM (if any) will pick the actual version.
-  implementation "com.google.firebase:firebase-messaging:23.4.1"
+  // The public native dispatcher accepts RemoteMessage, so host adapters need
+  // Firebase on their compile classpath as well as at runtime.
+  api "com.google.firebase:firebase-messaging:23.4.1"
 
   implementation "androidx.core:core-ktx:1.12.0"
   implementation "androidx.security:security-crypto:1.1.0-alpha06"

package/android/src/main/AndroidManifest.xml

@@ -9,6 +9,7 @@
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <application>
+        <receiver android:name="studio.usergist.feedback.UserGistNotificationDismissReceiver" android:exported="false" />
         <!-- Library-supplied FirebaseMessagingService. Hosts that already own
              FCM delivery must set userGistFirebaseServiceEnabled=false and
              forward tokens/messages through the public Push API. -->

package/android/src/main/java/studio/usergist/feedback/UserGistFirebaseMessagingService.kt

@@ -31,15 +31,30 @@ import org.json.JSONArray
  */
 class UserGistFirebaseMessagingService : FirebaseMessagingService() {
 
-  override fun onNewToken(token: String) {
-    super.onNewToken(token)
-    UserGistPushEventBus.emitToken(token)
+  override fun onNewToken(token: String) = handleToken(token)
+  override fun onMessageReceived(message: RemoteMessage) = handleMessage(this, message)
+  companion object {
+    @JvmStatic fun handleToken(token: String) = UserGistPushEventBus.emitToken(token)
+    @JvmStatic fun handleMessage(context: Context, message: RemoteMessage) {
+      if (!UserGistPushState.enabled(context)) return
+      // FCM already invokes this on its worker thread. Keep the service alive
+      // until presentation completes instead of leaving detached work behind.
+      UserGistMessageHandler(context.applicationContext).receive(message)
+    }
   }
+}
 
-  override fun onMessageReceived(remoteMessage: RemoteMessage) {
-    super.onMessageReceived(remoteMessage)
-
-    val payload = normalize(remoteMessage)
+private class UserGistMessageHandler(context: Context) : android.content.ContextWrapper(context) {
+  fun receive(remoteMessage: RemoteMessage) {
+    val recipient = remoteMessage.data["usergist_anonymous_id"] ?: UserGistPushState.anonymousId(this)
+    if (!UserGistPushState.accepts(this, recipient)) return
+    if (remoteMessage.data["usergist_silent"] == "1") {
+      UserGistPushState.receipt(this, "silent-ack", remoteMessage.data["usergist_ping_id"] ?: "")
+      return
+    }
+    if (!remoteMessage.data.containsKey("usergist_campaign_id")) return
+    UserGistPushState.receipt(this, "delivered", remoteMessage.data["usergist_delivery_id"] ?: "")
+    val payload = normalize(remoteMessage, recipient)
     UserGistPushEventBus.emitNotificationReceived(payload)
 
     // Surface a system notification when the user-visible content is set.
@@ -52,7 +67,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
       postSystemNotification(
         title = title,
         body = body,
-        data = remoteMessage.data
+        data = remoteMessage.data + ("usergist_anonymous_id" to recipient)
       )
     }
   }
@@ -74,17 +89,22 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     val pendingFlags = PendingIntent.FLAG_UPDATE_CURRENT or
       (if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) PendingIntent.FLAG_IMMUTABLE else 0)
     val contentIntent = launchIntent?.let {
-      PendingIntent.getActivity(this, 0, it, pendingFlags)
+      PendingIntent.getActivity(this, (data["usergist_delivery_id"] ?: data.toString()).hashCode(), it, pendingFlags)
     }
 
-    val notifId = (System.currentTimeMillis() % Int.MAX_VALUE).toInt()
+    val notifId = (data["usergist_delivery_id"] ?: data.toString()).hashCode()
     val builder = NotificationCompat.Builder(this, channelId)
-      .setSmallIcon(applicationInfo.icon.takeIf { it != 0 } ?: android.R.drawable.ic_dialog_info)
+      .setSmallIcon(packageManager.getApplicationInfo(packageName, android.content.pm.PackageManager.GET_META_DATA).metaData?.getInt("UserGistNotificationIcon", 0)?.takeIf { it != 0 } ?: android.R.drawable.ic_dialog_info)
       .setContentTitle(title)
       .setContentText(body)
       .setAutoCancel(true)
       .setContentIntent(contentIntent)
       .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+    data["usergist_badge"]?.let { raw ->
+      val badges = getSharedPreferences("usergist_push_badges", Context.MODE_PRIVATE)
+      val count = if (raw == "+1") badges.getInt("count", 0) + 1 else raw.toIntOrNull()
+      if (count != null && count >= 0) { builder.setNumber(count); badges.edit().putInt("count", count).apply() }
+    }
 
     val rawActions = data["usergist_actions"]
     if (!rawActions.isNullOrBlank() && launchIntent != null) {
@@ -107,8 +127,53 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
       }
     }
 
+    val color = packageManager.getApplicationInfo(packageName, android.content.pm.PackageManager.GET_META_DATA).metaData?.get("UserGistNotificationColor")
+    when (color) {
+      is Int -> builder.setColor(color)
+      is String -> runCatching { builder.setColor(android.graphics.Color.parseColor(color)) }
+    }
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O && data["usergist_sound"] != "none") {
+      val sound = data["usergist_sound"]
+      val custom = sound?.takeIf { it != "default" }?.let { resources.getIdentifier(it.substringBeforeLast('.'), "raw", packageName) } ?: 0
+      builder.setSound(if (custom != 0) android.net.Uri.parse("android.resource://$packageName/$custom") else android.media.RingtoneManager.getDefaultUri(android.media.RingtoneManager.TYPE_NOTIFICATION))
+    }
+    data["usergist_image_url"]?.let { raw ->
+      var connection: java.net.HttpURLConnection? = null
+      try {
+        val url = java.net.URL(raw)
+        if (url.protocol == "https") {
+          connection = url.openConnection() as java.net.HttpURLConnection
+          connection.connectTimeout = 4000; connection.readTimeout = 4000
+          connection.instanceFollowRedirects = false
+          if (connection.responseCode in 200..299) {
+            val bytes = connection.inputStream.use { stream ->
+              val out = java.io.ByteArrayOutputStream(); val buffer = ByteArray(8192)
+              while (out.size() <= 5 * 1024 * 1024) { val count = stream.read(buffer); if (count < 0) break; out.write(buffer, 0, count) }
+              out.toByteArray()
+            }
+            if (bytes.size <= 5 * 1024 * 1024) {
+              val bounds = android.graphics.BitmapFactory.Options().apply { inJustDecodeBounds = true }
+              android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+              val decode = android.graphics.BitmapFactory.Options().apply { inSampleSize = (maxOf(bounds.outWidth, bounds.outHeight) / 1024).coerceAtLeast(1) }
+              android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.size, decode)?.let { builder.setStyle(NotificationCompat.BigPictureStyle().bigPicture(it)) }
+            }
+          }
+        }
+      } catch (_: Exception) { /* Text notification still displays. */ }
+      finally { connection?.disconnect() }
+    }
+    val dismiss = Intent(this, UserGistNotificationDismissReceiver::class.java).apply {
+      data.forEach { (k, v) -> putExtra(k, v) }
+    }
+    builder.setDeleteIntent(PendingIntent.getBroadcast(this, notifId, dismiss, pendingFlags))
     val nm = NotificationManagerCompat.from(this)
+    if (!UserGistPushState.accepts(this, data["usergist_anonymous_id"]) || !nm.areNotificationsEnabled()) return
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && nm.getNotificationChannel(channelId)?.importance == NotificationManager.IMPORTANCE_NONE) return
     nm.notify(notifId, builder.build())
+    UserGistPushState.receipt(this, "displayed", data["usergist_delivery_id"] ?: "")
+    val displayed = Arguments.createMap()
+    displayed.putMap("data", Arguments.createMap().apply { data.forEach { (k, v) -> putString(k, v) } })
+    UserGistPushEventBus.emitNotificationDisplayed(displayed)
   }
 
   private fun ensureChannel(ctx: Context): String {
@@ -133,7 +198,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     return if (nm.getNotificationChannel(requested) != null) requested else ensureChannel(ctx)
   }
 
-  private fun normalize(msg: RemoteMessage): WritableMap {
+  private fun normalize(msg: RemoteMessage, recipient: String): WritableMap {
     val out = Arguments.createMap()
     msg.notification?.title?.let { out.putString("title", it) }
     msg.notification?.body?.let { out.putString("body", it) }
@@ -141,6 +206,7 @@ class UserGistFirebaseMessagingService : FirebaseMessagingService() {
     for ((k, v) in msg.data) {
       data.putString(k, v)
     }
+    data.putString("usergist_anonymous_id", recipient)
     out.putMap("data", data)
     val deliveryId = msg.data["delivery_id"] ?: msg.data["usergist_delivery_id"]
     if (deliveryId != null) out.putString("deliveryId", deliveryId)

package/android/src/main/java/studio/usergist/feedback/UserGistNotificationDismissReceiver.kt

@@ -0,0 +1,17 @@
+package studio.usergist.feedback
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+
+class UserGistNotificationDismissReceiver : BroadcastReceiver() {
+  override fun onReceive(context: Context, intent: Intent) {
+    if (!UserGistPushState.accepts(context, intent.getStringExtra("usergist_anonymous_id"))) return
+    UserGistPushState.receipt(context, "dismissed", intent.getStringExtra("usergist_delivery_id") ?: "")
+    val body = com.facebook.react.bridge.Arguments.createMap()
+    body.putMap("data", com.facebook.react.bridge.Arguments.createMap().apply {
+      intent.extras?.keySet()?.forEach { key -> intent.getStringExtra(key)?.let { putString(key, it) } }
+    })
+    UserGistPushEventBus.emitNotificationDismissed(body)
+  }
+}

package/android/src/main/java/studio/usergist/feedback/UserGistPushModule.kt

@@ -49,6 +49,12 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   }
 
   override fun getName(): String = NAME
+  override fun invalidate() {
+    reactApplicationContext.removeLifecycleEventListener(this)
+    reactApplicationContext.removeActivityEventListener(this)
+    UserGistPushEventBus.detach(reactApplicationContext)
+    super.invalidate()
+  }
 
   private val securePreferences by lazy {
     val masterKey = MasterKey.Builder(reactApplicationContext)
@@ -64,7 +70,8 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   }
 
   override fun onHostResume() {
-    currentActivity?.intent?.let { consumeNotificationIntent(it) }
+    UserGistPushState.retry(reactApplicationContext)
+    reactApplicationContext.currentActivity?.intent?.let { consumeNotificationIntent(it) }
   }
 
   override fun onHostPause() = Unit
@@ -77,6 +84,7 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   private fun consumeNotificationIntent(intent: Intent) {
     val extras = intent.extras ?: return
+    if (!UserGistPushState.accepts(reactApplicationContext, extras.getString("usergist_anonymous_id"))) return
     val keys = extras.keySet().filter { it.startsWith("usergist_") }
     if (keys.isEmpty()) return
     val body = Arguments.createMap()
@@ -99,8 +107,23 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   // MARK: - Exported methods
 
+  @ReactMethod
+  fun getPushConfiguration(promise: Promise) {
+    promise.resolve(Arguments.createMap().apply { putString("mode", UserGistPushState.mode(reactApplicationContext)) })
+  }
+
+  @ReactMethod
+  fun configurePushState(state: ReadableMap, promise: Promise) {
+    runCatching { UserGistPushState.configure(reactApplicationContext, org.json.JSONObject(state.toHashMap())) }
+      .onSuccess { promise.resolve(null) }.onFailure { promise.reject("push_state_failed", it) }
+  }
+
   @ReactMethod
   fun enablePush(_options: ReadableMap?, promise: Promise) {
+    if (UserGistPushState.mode(reactApplicationContext) == "disabled") {
+      promise.resolve(buildResult(false, "not_determined", null, "push_not_configured"))
+      return
+    }
     // Android < 13: notification permission is install-time, no runtime
     // prompt. We can short-circuit straight to the token fetch.
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) {
@@ -112,7 +135,7 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
       fetchTokenAndResolve(promise, status = "authorized")
       return
     }
-    val activity = currentActivity
+    val activity = reactApplicationContext.currentActivity
     if (activity == null) {
       // No activity: can't ask for permission. Resolve with current state.
       val granted = ActivityCompat.checkSelfPermission(
@@ -165,6 +188,8 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
 
   @ReactMethod
   fun disablePush(promise: Promise) {
+    UserGistPushState.disable(reactApplicationContext)
+    if (UserGistPushState.isExpo(reactApplicationContext)) { promise.resolve(null); return }
     FirebaseMessaging.getInstance().deleteToken()
       .addOnCompleteListener { promise.resolve(null) }
   }
@@ -233,10 +258,10 @@ class UserGistPushModule(reactContext: ReactApplicationContext) :
   // Required for RN's NativeEventEmitter API even though we emit from a
   // separate static bus — RN will warn otherwise.
   @ReactMethod
-  fun addListener(_eventName: String?) { /* no-op */ }
+  fun addListener(_eventName: String?) { UserGistPushEventBus.addListener() }
 
   @ReactMethod
-  fun removeListeners(_count: Double) { /* no-op */ }
+  fun removeListeners(_count: Double) { UserGistPushEventBus.removeListeners(_count.toInt()) }
 
   // MARK: - Internal
 
@@ -287,10 +312,12 @@ internal object UserGistPushEventBus {
   @Volatile private var reactContext: ReactApplicationContext? = null
   private val pending: MutableList<Pair<String, WritableMap>> = mutableListOf()
   private var initialNotification: WritableMap? = null
+  private var listenerCount = 0
 
   @Synchronized
   fun attach(ctx: ReactApplicationContext) {
     this.reactContext = ctx
+    if (listenerCount == 0) return
     val drained = pending.toList()
     pending.clear()
     for ((name, body) in drained) {
@@ -298,6 +325,20 @@ internal object UserGistPushEventBus {
     }
   }
 
+  @Synchronized
+  fun addListener() {
+    listenerCount++
+    // Drain after all JS subscriptions in this tick have been registered.
+    android.os.Handler(android.os.Looper.getMainLooper()).post {
+      synchronized(this) { if (listenerCount > 0) reactContext?.let { attach(it) } }
+    }
+  }
+  @Synchronized fun removeListeners(count: Int) { listenerCount = (listenerCount - count).coerceAtLeast(0) }
+  @Synchronized fun detach(ctx: ReactApplicationContext) { if (reactContext === ctx) { reactContext = null; listenerCount = 0 } }
+
+  fun emitNotificationDisplayed(body: WritableMap) = emit("UserGistPush:notificationDisplayed", body)
+  fun emitNotificationDismissed(body: WritableMap) = emit("UserGistPush:notificationDismissed", body)
+
   fun emitToken(token: String) {
     val map = Arguments.createMap()
     map.putString("token", token)
@@ -328,7 +369,7 @@ internal object UserGistPushEventBus {
   @Synchronized
   private fun emit(name: String, body: WritableMap) {
     val ctx = reactContext
-    if (ctx == null || !ctx.hasActiveReactInstance()) {
+    if (ctx == null || !ctx.hasActiveReactInstance() || listenerCount == 0) {
       if (pending.size >= 100) pending.removeAt(0)
       pending.add(name to body)
       return