@usergist/feedback-react-native 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to `@usergist/feedback-react-native` are documented here.
+Releases use [Semantic Versioning](https://semver.org/).
+
+## 0.1.0
+
+- Initial production React Native SDK.
+- Anonymous and identified-user sessions with consent-aware ingestion.
+- Offline event and mutation queues with bounded retries.
+- Feedback, survey, in-app message, feature-request, and push surfaces.
+- iOS and Android native push bridges plus notification-service extension.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 userGist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# @usergist/feedback-react-native
+
+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.
+
+## Install
+
+```bash
+npm install @usergist/feedback-react-native \
+  @react-native-async-storage/async-storage \
+  react-native-safe-area-context
+cd ios && pod install
+```
+
+AsyncStorage and `react-native-safe-area-context` are peer dependencies.
+Without AsyncStorage the SDK runs with an in-memory store, so queued events do
+not survive a relaunch.
+
+## Quick start
+
+```tsx
+import React from 'react'
+import { AppRegistry } from 'react-native'
+import { UserGist, UserGistProvider } from '@usergist/feedback-react-native'
+
+// Obtain this from your authenticated backend. It exchanges an rtk_ token at
+// POST /v1/apps/:appId/sdk/subject-tokens; never ship rtk_ tokens in the app.
+const identityResult = await UserGist.initAsync(
+  {
+    writeKey: 'rk_live_xxx',
+    apiUrl: 'https://api.usergist.com',
+    environment: 'production',
+    debug: __DEV__,
+  },
+  {
+    userId: 'user_42',
+    properties: { plan: 'pro' },
+    subjectToken: identifiedSubjectToken,
+  },
+)
+
+const consentSynchronized = await UserGist.setConsent({
+  analytics: true,
+  feedback: true,
+})
+
+function App() {
+  return (
+    <UserGistProvider>
+      {/* your app */}
+    </UserGistProvider>
+  )
+}
+
+AppRegistry.registerComponent('app', () => App)
+```
+
+## API
+
+| Method | Description |
+|---|---|
+| `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.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. |
+| `await UserGist.reset()` | Cancels in-flight, clears queue, rotates anonymous id, wipes caches, and resolves after the new anonymous session is ready. |
+| `UserGist.setThemeOverrides(theme)` | Global theme applied under per-prompt theme. |
+| `UserGist.flush()` | Best-effort flush. |
+| `UserGist.setDebug(boolean)` | Toggle the debug trace logger at runtime. |
+| `UserGist.setDiagnosticHandler(handler)` | Receive bounded diagnostics without raw user payloads. |
+| `UserGist.getAnonymousId()` | Returns the persisted anonymous id (21-char, URL-safe). |
+| `UserGist.getExternalId()` | Returns the current stable external account ID, or `null`. |
+| `UserGist.onPromptShown(cb)` / `UserGist.onResponse(cb)` | Observe prompt lifecycle. |
+
+Call and await `reset()` before identifying a different account on the same
+installation. Switching directly from one non-null external ID to another is
+rejected so two people cannot be merged accidentally.
+
+### Encrypted persistence
+
+By default, the SDK uses AsyncStorage for bounded event/campaign state and
+identity. Signed subject credentials and the durable mutation queue use the
+bundled Keychain/EncryptedSharedPreferences native store and never fall back to
+plaintext; if that native store is unavailable they remain process-memory only.
+Apps that want every persisted value encrypted can provide an encrypted
+key/value adapter **before** init:
+
+```ts
+UserGist.setStorageAdapter({
+  getItem: (key) => encryptedStore.getItem(key),
+  setItem: (key, value) => encryptedStore.setItem(key, value),
+  removeItem: (key) => encryptedStore.removeItem(key),
+})
+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.
+
+## Architecture
+
+The SDK is a singleton that orchestrates:
+`Storage · Subject session · Consent · Durable queues · Transport · Instruction inbox · Armed campaigns · Persistent user state · Modal UI · Lifecycle · Debug`.
+
+AsyncStorage is bounded but not encrypted. Use `setStorageAdapter` when all SDK
+state must be encrypted at rest, and never put credentials or secrets in event
+properties. Default email/phone/SSN/tax-id property keys are removed before
+persistence and again by the API.
+
+Public convenience methods contain their own failures and report bounded diagnostics through `setDiagnosticHandler`. Internal UI persistence hooks may reject so the bundled survey UI can show a pending/retry state instead of falsely reporting success.
+
+## Push integration modes
+
+`UserGist.enablePush()` uses the bundled automatic native integration by default. Apps that already own notification delegates or use another push SDK should use host-forwarded mode:
+
+```ts
+await UserGist.enablePush({
+  environment: 'production',
+  installDelegateProxy: false,
+})
+
+// Forward the token and message callbacks from the host integration.
+await Push.registerDeviceToken(token, Platform.OS === 'ios' ? 'ios' : 'android')
+Push.handleReceived({ data })
+Push.handleOpened({ data })
+```
+
+On Android, also disable the bundled `FirebaseMessagingService` when the host owns the FCM service. Set the application manifest placeholder `userGistFirebaseServiceEnabled=false` (or override/remove the library service in the app manifest). Automatic and host-forwarded modes must not both display the same notification.
+
+On iOS, `installDelegateProxy: false` prevents UserGist from intercepting `UIApplicationDelegate` and `UNUserNotificationCenter.delegate`. The host remains responsible for forwarding the APNs token and notification callbacks through `Push`.
+
+### JSON-driven in-app actions
+
+Dashboard-authored in-app CTAs and push action buttons can use the `json`
+action type. The SDK always records the generic button-tap event first, then
+passes the structured object to the host app. Keep business logic in the app
+so the same action can safely select a price, enable a feature, or route into a
+native flow:
+
+```ts
+function executeAction(action: Readonly<Record<string, unknown>>) {
+  if (action.type === 'enable_feature' && typeof action.feature === 'string') {
+    featureStore.enable(action.feature)
+  }
+}
+
+UserGist.setInAppHandlers({
+  onJsonAction: (action) => executeAction(action),
+})
+
+Push.setHandlers({
+  onJsonAction: (action) => executeAction(action),
+})
+```
+
+JSON actions are data, not executable code. Validate supported `type` values
+and fields in the host before changing app state.
+
+## iOS Notification Service Extension (NSE) — required for true delivery tracking
+
+The NSE runs in-process when each push arrives, BEFORE the system displays it.
+Without it, on iOS we cannot distinguish "delivered" from "user opened the
+notification" — `delivered_at` only fills when the user actually taps.
+
+### One-time Xcode setup
+
+1. **File → New → Target → Notification Service Extension**
+   - Name: `UserGistNotificationServiceExtension`
+   - Bundle id: `<your-app-bundle>.UserGistNotificationServiceExtension`
+2. **Replace the auto-generated `NotificationService.swift`** with:
+   ```swift
+   import UserNotifications
+   import UserGistFeedbackExtension
+
+   class NotificationService: UserGistNotificationService { }
+   ```
+3. **Configure the NSE target's Info.plist** (or write to the App Group's
+   `UserDefaults` from the main app — preferred, supports rotation):
+   - `UserGistWriteKey` — required; same write key the main SDK uses.
+   - `UserGistApiUrl` — optional; defaults to `https://api.usergist.com`.
+   - `UserGistAppGroup` — optional; App Group id shared with main app.
+   - `UserGistAnonymousId` — populated by main SDK at init via App Group.
+4. **Add `pod 'UserGistFeedbackExtension'`** to the NSE target stanza in your
+   `Podfile` and run `pod install`.
+
+The `UserGistNotificationService` base class:
+- Detects silent reachability pings (`usergist_silent: "1"`) and acks them
+  — the system shows nothing.
+- Beacons `POST /v1/sdk/push/delivered` with the `usergist.deliveryId` so
+  we record true delivered_at, distinct from when the user opens.
+- Falls back to an App Group ledger if the network beacon fails; the main
+  app drains it on next foreground.
+- Downloads any rich-media `imageUrl` and attaches it as a
+  `UNNotificationAttachment`.
+
+## Android NotificationChannels
+
+Android 8+ requires every notification to belong to a registered channel —
+notifications without a channel are silently dropped by the OS. The bundled
+Android service creates a `usergist_default` fallback channel automatically.
+When a push names a dashboard-configured `usergist_channel_id`, the service
+uses it if the host app has already created that channel and otherwise falls
+back safely. Host-forwarded integrations can call `await Push.fetchChannels()`
+at startup and create/update those definitions with their notification library.
+
+## Forward `applicationDidBecomeActive` / `onResume`
+
+Automatic mode sends this beacon from the SDK's foreground listener. In
+host-forwarded mode, call `Push.appDidBecomeActive()` from your foreground hook so the
+server's reachability worker knows this device is alive — skips the next
+silent-ping cycle for this user (saves provider quota + battery).
+
+## Compatibility and privacy decisions
+
+- Transport bodies use plain JSON so the SDK does not add a native compression dependency.
+- Device model is not collected by default. Send an approved, non-sensitive
+  property if your product genuinely needs model-level analysis.
+- Anonymous IDs use a dependency-free, cryptographically random 21-character
+  URL-safe generator compatible with nanoid identifiers.
+
+## Testing hooks
+
+`UserGist.__internal_state()` exposes `{ config, identity, consent, queueSize, triggerCount, frequencyCaps, traces }`. Unstable; do not rely on in production code.
+
+## License
+
+MIT

package/UserGistFeedback.podspec

@@ -0,0 +1,31 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name             = 'UserGistFeedback'
+  s.version          = package['version']
+  s.summary          = package['description']
+  s.description      = package['description']
+  s.homepage         = 'https://github.com/Future-Picnic/usergist-js'
+  s.license          = { :type => 'MIT', :file => 'LICENSE' }
+  s.authors          = { 'userGist' => 'engineering@usergist.com' }
+  s.platforms        = { :ios => '13.0' }
+  s.source           = { :git => 'https://github.com/Future-Picnic/usergist-js.git', :tag => "v#{s.version}" }
+
+  s.requires_arc     = true
+  s.swift_version    = '5.7'
+
+  # Default subspec — what RN autolinking picks up for the host app target.
+  s.default_subspec = 'Core'
+
+  # ---------- Core subspec (for the main app target) ----------
+  # 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.frameworks   = 'UIKit', 'UserNotifications', 'Security'
+    core.dependency 'React-Core'
+  end
+
+end

package/UserGistFeedbackExtension.podspec

@@ -0,0 +1,23 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+# The Notification Service Extension is deliberately a separate pod. CocoaPods
+# gives every subspec the root pod's Swift module name, which causes Xcode to
+# infer circular dependencies when the app bridge and extension are embedded in
+# the same workspace. This pod contains no React Native runtime dependency.
+Pod::Spec.new do |s|
+  s.name             = 'UserGistFeedbackExtension'
+  s.version          = package['version']
+  s.summary          = 'UserGist notification service extension support'
+  s.description      = 'Lightweight iOS notification service extension support for UserGist React Native applications.'
+  s.homepage         = 'https://github.com/Future-Picnic/usergist-js'
+  s.license          = { :type => 'MIT', :file => 'LICENSE' }
+  s.authors          = { 'userGist' => 'engineering@usergist.com' }
+  s.platforms        = { :ios => '13.0' }
+  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.frameworks       = 'UserNotifications'
+end

package/android/build.gradle

@@ -0,0 +1,92 @@
+// Android build module for @usergist/feedback-react-native.
+//
+// What this module owns:
+//   - The native Kotlin React Native module (UserGistPushModule)
+//   - A FirebaseMessagingService subclass that auto-registers via the
+//     library's AndroidManifest (manifest-merger merges it into the host).
+//   - A transitive dep on com.google.firebase:firebase-messaging so the
+//     host app does NOT need @react-native-firebase/messaging — they
+//     only need their own google-services.json + the gms plugin.
+//
+// Convention: matches what most React Native libraries do (react-native-permissions, etc.).
+
+buildscript {
+  ext.getExtOrDefault = { name ->
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["UserGistPush_" + name]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:7.2.1"
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.22"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+def isNewArchitectureEnabled() {
+  return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+}
+
+android {
+  namespace "studio.usergist.feedback"
+  compileSdkVersion getExtOrDefault('compileSdkVersion')?.toInteger() ?: 34
+  buildToolsVersion getExtOrDefault('buildToolsVersion') ?: '34.0.0'
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault('minSdkVersion')?.toInteger() ?: 23
+    targetSdkVersion getExtOrDefault('targetSdkVersion')?.toInteger() ?: 34
+    consumerProguardFiles 'consumer-rules.pro'
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+    manifestPlaceholders = [userGistFirebaseServiceEnabled: "true"]
+  }
+
+  buildFeatures {
+    buildConfig true
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+
+  sourceSets {
+    main {
+      manifest.srcFile "src/main/AndroidManifest.xml"
+      java.srcDirs = ['src/main/java']
+    }
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  // FCM token + RemoteMessage delivery. Bundled transitively so consumer
+  // apps don't add @react-native-firebase/messaging themselves; they only
+  // need their own google-services.json + the com.google.gms.google-services
+  // 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"
+
+  implementation "androidx.core:core-ktx:1.12.0"
+  implementation "androidx.security:security-crypto:1.1.0-alpha06"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,5 @@
+# Preserve the manifest-instantiated FCM service and React Native module in
+# minified host release builds.
+-keep class studio.usergist.feedback.UserGistFirebaseMessagingService { *; }
+-keep class studio.usergist.feedback.UserGistPushModule { *; }
+-keep class studio.usergist.feedback.UserGistPushPackage { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,31 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Required for Firebase Cloud Messaging delivery. The host app's
+         google-services.json + com.google.gms.google-services plugin
+         provide the actual configuration. -->
+
+    <!-- Android 13+ runtime permission for showing notifications. -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+    <application>
+        <!-- Library-supplied FirebaseMessagingService. Hosts that already own
+             FCM delivery must set userGistFirebaseServiceEnabled=false and
+             forward tokens/messages through the public Push API. -->
+        <service
+            android:name=".UserGistFirebaseMessagingService"
+            android:enabled="${userGistFirebaseServiceEnabled}"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+
+        <!-- Default notification channel applied when the host hasn't
+             defined one. Consumers can override by declaring their own
+             default-channel meta-data (auto-merged with theirs winning). -->
+        <meta-data
+            android:name="com.google.firebase.messaging.default_notification_channel_id"
+            android:value="usergist_default" />
+    </application>
+</manifest>

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

@@ -0,0 +1,153 @@
+package studio.usergist.feedback
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import androidx.core.app.NotificationCompat
+import androidx.core.app.NotificationManagerCompat
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+import org.json.JSONArray
+
+/**
+ * Library-supplied FirebaseMessagingService.  Auto-registered via the
+ * library AndroidManifest's manifest-merger entry — consumer apps don't
+ * write any Firebase code.
+ *
+ *  - `onNewToken`        : forward to JS so the SDK re-registers with the API.
+ *  - `onMessageReceived` : (a) emit a `notificationReceived` JS event so
+ *                         the host can react, (b) post a system notification
+ *                         when the host app is backgrounded so the user sees
+ *                         the message even when no Activity is alive.
+ *
+ * If the host app already declares its own FirebaseMessagingService, it must
+ * disable this service with the `userGistFirebaseServiceEnabled` manifest
+ * placeholder and forward tokens/messages through the public Push API.
+ */
+class UserGistFirebaseMessagingService : FirebaseMessagingService() {
+
+  override fun onNewToken(token: String) {
+    super.onNewToken(token)
+    UserGistPushEventBus.emitToken(token)
+  }
+
+  override fun onMessageReceived(remoteMessage: RemoteMessage) {
+    super.onMessageReceived(remoteMessage)
+
+    val payload = normalize(remoteMessage)
+    UserGistPushEventBus.emitNotificationReceived(payload)
+
+    // Surface a system notification when the user-visible content is set.
+    // Background / killed-state delivery on Android requires explicit
+    // NotificationManager.notify() — RemoteMessage doesn't auto-display.
+    val notification = remoteMessage.notification
+    val title = notification?.title ?: remoteMessage.data["title"] ?: remoteMessage.data["usergist_title"]
+    val body = notification?.body ?: remoteMessage.data["body"] ?: remoteMessage.data["usergist_body"]
+    if (title != null || body != null) {
+      postSystemNotification(
+        title = title,
+        body = body,
+        data = remoteMessage.data
+      )
+    }
+  }
+
+  private fun postSystemNotification(title: String?, body: String?, data: Map<String, String>) {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
+      checkSelfPermission(android.Manifest.permission.POST_NOTIFICATIONS) != android.content.pm.PackageManager.PERMISSION_GRANTED
+    ) return
+    val channelId = resolveChannel(this, data["usergist_channel_id"] ?: data["channel_id"])
+    val launchIntent = packageManager?.getLaunchIntentForPackage(packageName)?.apply {
+      flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+      // Forward delivery_id + usergist_delivery_id so when the user taps and
+      // the app launches we can fire `$push_opened` with the right id.
+      data.forEach { (k, v) ->
+        val key = if (k.startsWith("usergist_")) k else "usergist_$k"
+        putExtra(key, v)
+      }
+    }
+    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)
+    }
+
+    val notifId = (System.currentTimeMillis() % Int.MAX_VALUE).toInt()
+    val builder = NotificationCompat.Builder(this, channelId)
+      .setSmallIcon(applicationInfo.icon.takeIf { it != 0 } ?: android.R.drawable.ic_dialog_info)
+      .setContentTitle(title)
+      .setContentText(body)
+      .setAutoCancel(true)
+      .setContentIntent(contentIntent)
+      .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+
+    val rawActions = data["usergist_actions"]
+    if (!rawActions.isNullOrBlank() && launchIntent != null) {
+      runCatching {
+        val actions = JSONArray(rawActions)
+        for (index in 0 until actions.length()) {
+          val action = actions.optJSONObject(index) ?: continue
+          val label = action.optString("label").takeIf { it.isNotBlank() } ?: continue
+          val actionIntent = Intent(launchIntent).apply {
+            putExtra("usergist_action_identifier", "usergist_action_$index")
+          }
+          val actionPendingIntent = PendingIntent.getActivity(
+            this,
+            notifId * 10 + index + 1,
+            actionIntent,
+            pendingFlags,
+          )
+          builder.addAction(0, label, actionPendingIntent)
+        }
+      }
+    }
+
+    val nm = NotificationManagerCompat.from(this)
+    nm.notify(notifId, builder.build())
+  }
+
+  private fun ensureChannel(ctx: Context): String {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return DEFAULT_CHANNEL_ID
+    val nm = ctx.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    if (nm.getNotificationChannel(DEFAULT_CHANNEL_ID) == null) {
+      val channel = NotificationChannel(
+        DEFAULT_CHANNEL_ID,
+        "Notifications",
+        NotificationManager.IMPORTANCE_DEFAULT
+      )
+      nm.createNotificationChannel(channel)
+    }
+    return DEFAULT_CHANNEL_ID
+  }
+
+  private fun resolveChannel(ctx: Context, requested: String?): String {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O || requested.isNullOrBlank()) {
+      return ensureChannel(ctx)
+    }
+    val nm = ctx.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    return if (nm.getNotificationChannel(requested) != null) requested else ensureChannel(ctx)
+  }
+
+  private fun normalize(msg: RemoteMessage): WritableMap {
+    val out = Arguments.createMap()
+    msg.notification?.title?.let { out.putString("title", it) }
+    msg.notification?.body?.let { out.putString("body", it) }
+    val data = Arguments.createMap()
+    for ((k, v) in msg.data) {
+      data.putString(k, v)
+    }
+    out.putMap("data", data)
+    val deliveryId = msg.data["delivery_id"] ?: msg.data["usergist_delivery_id"]
+    if (deliveryId != null) out.putString("deliveryId", deliveryId)
+    return out
+  }
+
+  companion object {
+    const val DEFAULT_CHANNEL_ID = "usergist_default"
+  }
+}