react-native-qpush 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,440 @@
-# Temporary Holding Version
+# react-native-qpush
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native SDK for **QPush**, the self-hosted, OneSignal-compatible push notification server.
+
+The API mirrors the OneSignal React Native SDK v5 (`OneSignal.*` becomes `QPush.*`), so if you have used OneSignal you already know how to use it:
+
+```ts
+import { QPush, LogLevel } from 'react-native-qpush';
+
+QPush.Debug.setLogLevel(LogLevel.Verbose);
+QPush.initialize('YOUR_APP_ID'); // qpush cloud: https://qpush.dev/api/v1
+QPush.Notifications.requestPermission(true);
+```
+
+- Android: FCM, with **no `google-services.json` required**. FCM credentials come from your QPush dashboard.
+- iOS: APNs, with no AppDelegate changes, plus a Notification Service Extension for images, action buttons and confirmed delivery.
+- Expo: config plugin for development builds and EAS.
+- Works on the old architecture and on the New Architecture (bridgeless) through React Native's interop layer.
+
+---
+
+## Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Android setup](#android-setup)
+4. [iOS setup (bare React Native)](#ios-setup-bare-react-native)
+5. [Expo setup](#expo-setup)
+6. [Initialization](#initialization)
+7. [API reference](#api-reference)
+8. [How it works](#how-it-works)
+9. [Migrating from OneSignal](#migrating-from-onesignal)
+10. [Troubleshooting](#troubleshooting)
+
+---
+
+## Requirements
+
+| | Minimum |
+| --- | --- |
+| React Native | 0.71 |
+| Android | minSdk 21, compileSdk 34 recommended |
+| iOS | 13.0, Xcode 15+ |
+| Expo | SDK 50+ with a [development build](https://docs.expo.dev/develop/development-builds/introduction/). Expo Go is not supported. |
+| QPush server | An app with Android (FCM) and/or iOS (APNs) credentials configured in the dashboard |
+
+## Installation
+
+```sh
+npm install react-native-qpush
+# or
+yarn add react-native-qpush
+```
+
+Bare React Native: `cd ios && pod install`. Expo: see [Expo setup](#expo-setup).
+
+---
+
+## Android setup
+
+There is nothing to configure. Autolinking registers the module, and the library's manifest declares:
+
+- `POST_NOTIFICATIONS` (Android 13+ runtime permission), `INTERNET`, `ACCESS_NETWORK_STATE`, `VIBRATE`
+- `QPushMessagingService`, a `FirebaseMessagingService` that renders QPush notifications even when the app is killed
+- `QPushNotificationOpenActivity`, the invisible activity that handles notification taps (Android 12+ compliant)
+
+**FCM without `google-services.json`.** On every cold start the SDK downloads `android_params.js` from your server and initializes a secondary `FirebaseApp` named `QPUSH_SDK_FCM_APP` using the FCM credentials in your QPush dashboard. OneSignal works the same way. If the dashboard has no FCM credentials, the SDK uses the app's default `FirebaseApp` when one exists (that is, when the app has `google-services.json`).
+
+### Optional: notification icon
+
+Android shows the small icon as a white silhouette. Add a monochrome drawable named **`ic_stat_qpush_default`** (for example in `android/app/src/main/res/drawable-*/ic_stat_qpush_default.png`). The SDK picks icons in this order:
+
+1. the `small_icon` sent with the notification (a drawable name)
+2. `ic_stat_qpush_default`
+3. the app icon
+
+### Optional: default accent color
+
+```xml
+<!-- android/app/src/main/AndroidManifest.xml, inside <application> -->
+<meta-data android:name="com.qpush.NotificationAccentColor.DEFAULT" android:value="FF0070F3" />
+```
+
+### Optional: disable opening URLs on tap
+
+```xml
+<meta-data android:name="com.qpush.suppressLaunchURLs" android:value="true" />
+```
+
+You can also change it at runtime with `QPush.Notifications.setAutoOpenUrls(false)`.
+
+### Optional: Firebase BoM version
+
+The SDK uses Firebase BoM `33.16.0` by default, the newest line that still supports minSdk 21. If your app's minSdk is 23 or higher you can use a newer BoM:
+
+```groovy
+// android/build.gradle
+ext {
+  qpushFirebaseBomVersion = "34.19.0"
+}
+```
+
+If your app already uses Firebase, Gradle resolves the highest `firebase-messaging` version on its own.
+
+### Notification channels
+
+Notifications without `channel_id` go to the **`qpush_default`** channel, named "Notifications" with high importance. To localize the name, override the string resource `qpush_default_channel_name`. To use your own channels (for example with custom sounds), create them in your app and send their `channel_id`. If a channel does not exist on the device, the default channel is used.
+
+---
+
+## iOS setup (bare React Native)
+
+### 1. Install the pod
+
+```sh
+cd ios && pod install
+```
+
+The SDK swizzles the app delegate to capture the APNs token, the same technique OneSignal uses. It also installs itself as the `UNUserNotificationCenter` delegate and forwards everything that is not a QPush notification to any delegate that your app or other libraries set. You do not need to edit `AppDelegate`.
+
+### 2. Add capabilities to the app target
+
+In Xcode, select your app target, open **Signing & Capabilities**, and add:
+
+1. **Push Notifications**
+2. **Background Modes**, then check **Remote notifications**
+3. **App Groups**, then add **`group.<your bundle id>.qpush`** (for example `group.com.acme.app.qpush`)
+
+The App Group lets the Notification Service Extension read the app id, server URL and subscription id that the SDK saves when it initializes. To use a different group name, set it as `QPushAppGroup` (String) in the Info.plist of both the app and the extension.
+
+### 3. Add the Notification Service Extension
+
+The extension downloads notification images, registers action buttons and confirms delivery (`report_received`) even when the app is not running. Without it, notifications are still shown, but with no image and no buttons, and delivery is only reported while the app is open.
+
+1. In Xcode choose **File > New > Target…** and pick **Notification Service Extension**.
+2. Set the product name to **`QPushNotificationServiceExtension`** and the language to **Swift**. Click **Finish**, then **Don't Activate** when Xcode asks about the scheme.
+3. Select the new target:
+   - Under **General > Minimum Deployments**, use the same iOS version as your app (13.0 or later).
+   - Under **Signing & Capabilities**, add **App Groups** with the same `group.<your bundle id>.qpush`.
+   - Make sure **Version** and **Build** match your app. App Store Connect rejects mismatches.
+4. Replace the generated `QPushNotificationServiceExtension/NotificationService.swift` with the template from
+   [`node_modules/react-native-qpush/ios_nse_template/NotificationService.swift`](ios_nse_template/NotificationService.swift).
+5. Add the helper pod to the extension target at the end of your `ios/Podfile`:
+
+   ```ruby
+   target 'QPushNotificationServiceExtension' do
+     pod 'QPushPushExtension', :path => '../node_modules/react-native-qpush/ios/Extension'
+   end
+   ```
+
+6. Run `cd ios && pod install`.
+
+If you would rather not use the pod, add `node_modules/react-native-qpush/ios/Extension/QPushNotificationServiceExtension.swift` to the extension target instead. The template compiles either way.
+
+### iOS details
+
+- The token is the hex-encoded APNs device token.
+- `test_type` is detected automatically from `embedded.mobileprovision` (`aps-environment = development` gives `1`, ad-hoc gives `2`, App Store and TestFlight give `null`). Simulators report `1`. With the APNs environment set to `auto` in the dashboard, the server picks sandbox or production on its own.
+- The badge is cleared when the app opens, and `badge_count: 0` is sent to the server.
+- To disable opening URLs on tap at build time, set `QPush_suppress_launch_urls` (Boolean `YES`) in Info.plist.
+
+---
+
+## Expo setup
+
+Expo Go does not include native code, so you need a [development build](https://docs.expo.dev/develop/development-builds/introduction/).
+
+```sh
+npx expo install react-native-qpush expo-dev-client
+```
+
+Add the plugin to `app.json` / `app.config.js`:
+
+```json
+{
+  "expo": {
+    "ios": { "bundleIdentifier": "com.acme.app" },
+    "android": { "package": "com.acme.app" },
+    "plugins": [
+      ["react-native-qpush", { "mode": "development" }]
+    ]
+  }
+}
+```
+
+Then:
+
+```sh
+npx expo prebuild
+npx expo run:ios     # or: eas build --profile development
+npx expo run:android
+```
+
+The plugin, modeled on `onesignal-expo-plugin`, does all of the [iOS setup](#ios-setup-bare-react-native) for you:
+
+- adds the `aps-environment` entitlement and the App Group `group.<bundle id>.qpush`
+- enables Background Modes / `remote-notification`
+- creates the `QPushNotificationServiceExtension` target from the template, with the App Group, the matching version and build number, and the `QPushPushExtension` pod in the Podfile
+- registers the extension in `extra.eas.build.experimental.ios.appExtensions` so EAS Build manages its provisioning profile
+
+### Plugin options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `"development" \| "production"` | `"development"` | Value of the `aps-environment` entitlement. Use `"production"` for TestFlight and App Store builds. |
+| `devTeam` | `string` | – | Apple Team ID applied to the extension target. |
+| `iPhoneDeploymentTarget` | `string` | `"15.1"` | Deployment target of the extension. Match your app's. |
+| `disableNSE` | `boolean` | `false` | Skip the Notification Service Extension. |
+| `nseFilePath` | `string` | – | Path to your own `NotificationService.swift`, used instead of the template. |
+| `appGroup` | `string` | `group.<bundle id>.qpush` | Custom App Group name. |
+| `suppressLaunchUrls` | `boolean` | `false` | Do not open the notification URL on tap (iOS Info.plist switch). |
+| `smallIcon` | `string` | – | Path to a PNG copied as the Android `ic_stat_qpush_default` drawable. |
+| `accentColor` | `string` | – | Android default accent color (`#RRGGBB` or `AARRGGBB`). |
+
+---
+
+## Initialization
+
+Call `initialize` once, as early as possible. Calling it in your entry file or at module scope of `App.tsx` makes sure clicks that cold-start the app are delivered. You can call any other method right after it, because calls are queued until the SDK has loaded its state.
+
+```ts
+import { QPush, LogLevel } from 'react-native-qpush';
+
+QPush.Debug.setLogLevel(LogLevel.Warn);
+QPush.initialize('YOUR_APP_ID', {
+  serverUrl: 'https://qpush.dev/api/v1', // qpush cloud (the default); change only if you self-host
+});
+
+// Ask for permission. The prompt shows on iOS and Android 13+; earlier
+// Android versions grant it automatically.
+QPush.Notifications.requestPermission(true);
+```
+
+What `initialize` does:
+
+1. Saves the config (also for native code and the iOS extension) and fetches `android_params.js` / `ios_params.js`.
+2. Gets the push token: FCM through the dashboard credentials, or APNs.
+3. Creates or refreshes the user and this device's subscription.
+4. Starts session tracking: a new session on cold start or after 30 seconds or more in the background, plus foreground time.
+
+---
+
+## API reference
+
+### `QPush`
+
+| Method | Description |
+| --- | --- |
+| `initialize(appId: string, options?: { serverUrl?: string; logLevel?: LogLevel }): void` | Initializes the SDK. `serverUrl` defaults to the qpush cloud (`https://qpush.dev/api/v1`). |
+| `login(externalId: string): void` | Identifies the user with your user id (`external_id`). If the device's user is anonymous, it becomes the identified user and keeps its tags. If another user already has that `external_id`, the device moves to that user and its tags are loaded. |
+| `logout(): void` | Creates a new anonymous user that owns this device's subscription. Does nothing when no user is logged in. |
+| `setConsentRequired(required: boolean): void` | When `true`, nothing is sent to the server until `setConsentGiven(true)`. Call it **before** `initialize`. |
+| `setConsentGiven(given: boolean): void` | Grants or revokes consent. Both settings persist across launches. |
+
+### `QPush.Debug`
+
+| Method | Description |
+| --- | --- |
+| `setLogLevel(level: LogLevel): void` | `None`, `Fatal`, `Error`, `Warn` (default), `Info`, `Debug`, `Verbose`. Applies to JS and native logs. |
+
+### `QPush.Notifications`
+
+| Method | Description |
+| --- | --- |
+| `requestPermission(fallbackToSettings: boolean): Promise<boolean>` | Shows the OS prompt. When the prompt can no longer be shown (permission permanently denied) and `fallbackToSettings` is `true`, it opens the app's notification settings and resolves when the user comes back. |
+| `getPermissionAsync(): Promise<boolean>` | Whether the app can currently show notifications. |
+| `permissionNative(): Promise<NotificationPermission>` | `NotDetermined`, `Denied`, `Authorized`, `Provisional` or `Ephemeral`. |
+| `canRequestPermission(): Promise<boolean>` | Whether `requestPermission` would show the OS prompt. |
+| `registerForProvisionalAuthorization(): Promise<boolean>` | iOS 12+ quiet notifications without a prompt. On Android it reports the current permission. |
+| `addEventListener(event, listener)` / `removeEventListener(event, listener)` | See [events](#notification-events). |
+| `clearAll(): void` | Removes all QPush notifications from the notification center (and clears the badge on iOS). |
+| `removeNotification(notificationId: string): void` | Removes one notification by its QPush id. |
+| `removeGroupedNotifications(groupKey: string): void` | Removes an Android group or an iOS `thread-id`. |
+| `setAutoOpenUrls(enabled: boolean): void` | Turns opening of `url` on tap on or off. Persisted natively, so it also applies to cold starts. Default is enabled. |
+
+#### Notification events
+
+```ts
+import { QPush, NotificationClickEvent, NotificationWillDisplayEvent } from 'react-native-qpush';
+
+// Tap on the notification or on an action button.
+// Clicks that happen before any listener is added (cold start) are queued and
+// delivered as soon as you add the first listener.
+QPush.Notifications.addEventListener('click', (event: NotificationClickEvent) => {
+  const { notification, result } = event;
+  console.log(notification.notificationId, notification.additionalData);
+  console.log(result.actionId); // id of the tapped button, if any
+  console.log(result.url);      // button url wins over the notification url
+});
+
+// Notification received while the app is in the foreground.
+QPush.Notifications.addEventListener('foregroundWillDisplay', (event: NotificationWillDisplayEvent) => {
+  event.preventDefault(); // must be called synchronously
+  const notification = event.getNotification();
+  if (shouldShow(notification)) notification.display(); // show it later, within 25 s
+});
+
+// Permission granted or revoked (also detected when returning from system settings).
+QPush.Notifications.addEventListener('permissionChange', (granted: boolean) => {});
+```
+
+If no listener calls `preventDefault()`, the notification is shown. If the JS runtime does not answer within about one second, it is also shown.
+
+`QPushNotification` fields: `notificationId`, `title`, `subtitle`, `body`, `launchURL`, `additionalData`, `bigPicture`, `largeIcon`, `smallIcon`, `accentColor`, `sound`, `channelId`, `priority`, `groupKey`, `collapseId`, `visibility`, `badge`, `category`, `interruptionLevel`, `relevanceScore`, `contentAvailable`, `actionButtons` (`{ id, text, icon?, url? }[]`), `rawPayload`, plus the method `display()`.
+
+### `QPush.User`
+
+| Method | Description |
+| --- | --- |
+| `addTag(key: string, value: string \| number \| boolean): void` | Adds or updates a tag. Values are stored as strings. |
+| `addTags(tags: Record<string, string \| number \| boolean>): void` | Same for several tags. Only values that changed are sent. |
+| `removeTag(key: string): void` / `removeTags(keys: string[]): void` | Removes tags. |
+| `getTags(): Promise<Record<string, string>>` | Local copy of the tags, refreshed from the server on every app start and on login. |
+| `addAlias(label: string, id: string): void` / `addAliases(record)` | Adds custom aliases (for example `crm_id`). Use `QPush.login` for `external_id`. |
+| `removeAlias(label: string): void` / `removeAliases(labels)` | Removes aliases. |
+| `setLanguage(language: string): void` | ISO 639-1 code. Defaults to the device language. |
+| `getQPushId(): Promise<string \| null>` | The QPush user id (`qpush_id`). `getOnesignalId()` is an alias. |
+| `getExternalId(): Promise<string \| null>` | The logged-in `external_id`. |
+| `addEventListener('change', listener)` / `removeEventListener` | `{ current: { qpushId, externalId } }` |
+
+### `QPush.User.pushSubscription`
+
+| Method | Description |
+| --- | --- |
+| `getIdAsync(): Promise<string \| null>` | This device's subscription id. |
+| `getTokenAsync(): Promise<string \| null>` | FCM token (Android) or hex APNs token (iOS). |
+| `getOptedInAsync(): Promise<boolean>` | `true` when there is a token, the permission is granted, and you have not called `optOut()`. |
+| `optIn(): void` | Re-enables push for this device. It prompts for permission if the user was never asked. |
+| `optOut(): void` | Stops push to this device without touching the OS permission. |
+| `addEventListener('change', listener)` / `removeEventListener` | `{ previous: { id, token, optedIn }, current: { id, token, optedIn } }` |
+
+---
+
+## How it works
+
+- **A single TypeScript state machine** handles the user, subscription, sessions and every HTTP call. Native code only does what has to be native: the push token, permission, rendering, and handling taps and receipts.
+- **Persisted operation queue.** Every server change (create user, tags, aliases, login, subscription updates, session counters) is written to a queue saved in SharedPreferences or UserDefaults through the native module (AsyncStorage is not used). Operations run in order and are merged when possible (for example several `addTag` calls become one `PATCH`). `429` and `5xx` responses are retried with exponential backoff, up to 5 attempts. Network failures are retried until they succeed, so changes made offline reach the server later, even after the app restarts.
+- **Users are referenced locally.** An operation queued before `login`/`logout` always applies to the user that existed when you called it.
+- **Receipts and opens are reported natively** (`PUT /notifications/{id}/report_received` and `PUT /notifications/{id}`). They are sent from the Android messaging service and notification activity, and from the iOS extension and notification delegate, so they work even when the JS runtime is not running.
+
+All endpoints and payloads follow the [QPush SDK protocol](https://github.com/qpush/qpush/blob/main/docs/sdk-protocol.md).
+
+---
+
+## Migrating from OneSignal
+
+| OneSignal | QPush |
+| --- | --- |
+| `OneSignal.initialize(appId)` | `QPush.initialize(appId, { serverUrl })` |
+| `OneSignal.Notifications.*` | `QPush.Notifications.*` (same events: `click`, `foregroundWillDisplay`, `permissionChange`) |
+| `OneSignal.User.*` | `QPush.User.*` |
+| `OneSignal.User.getOnesignalId()` | `QPush.User.getQPushId()` (or `getOnesignalId()`) |
+| `OneSignal.login` / `logout` | `QPush.login` / `logout` |
+| `onesignal-expo-plugin` | `react-native-qpush` plugin (same idea, `mode` option) |
+| `OneSignalNotificationServiceExtension` | `QPushNotificationServiceExtension` |
+| App Group `group.<bundle>.onesignal` | `group.<bundle>.qpush` |
+
+Remove `react-native-onesignal` before installing this package. Both SDKs register a `FirebaseMessagingService` on Android and a notification delegate on iOS.
+
+---
+
+## Troubleshooting
+
+Turn on verbose logs first:
+
+```ts
+QPush.Debug.setLogLevel(LogLevel.Verbose);
+```
+
+Then watch `adb logcat -s QPush` on Android or the Xcode console (filter `[QPush]`) on iOS.
+
+**"The native module 'QPushPush' is not available"**
+Rebuild the app after installing (`pod install` on iOS). Expo Go is not supported, so use a development build.
+
+**Android: no token / `notification_types = -3`**
+- Add Android (FCM) credentials to the app in the QPush dashboard (project id, app id, API key, sender id), or add `google-services.json` to use the default FirebaseApp.
+- The device or emulator needs Google Play services. Use an emulator image "with Google Play".
+- If the dashboard credentials were added after the first launch, restart the app or bring it to the foreground. The SDK retries registration.
+
+**Android: notifications do not appear**
+- Android 13+: call `QPush.Notifications.requestPermission(true)`.
+- Check that the channel you send in `channel_id` exists, or leave it empty to use `qpush_default`.
+- Another library with its own `FirebaseMessagingService`, such as `@react-native-firebase/messaging`, can take QPush's messages, because only one service receives them. Forward them from your service:
+
+  ```kotlin
+  override fun onMessageReceived(message: RemoteMessage) {
+    if (com.qpush.reactnative.QPushMessagingService.handleMessage(this, message)) return
+    // ...your handling
+  }
+  override fun onNewToken(token: String) {
+    com.qpush.reactnative.QPushMessagingService.handleNewToken(this, token)
+  }
+  ```
+
+**iOS: no token / `notification_types = -10`**
+- Enable the **Push Notifications** capability and make sure the provisioning profile includes it.
+- Simulators only get tokens on iOS 16+ on Apple silicon Macs. Use a real device otherwise.
+- `-10` means APNs registration failed. Check the Xcode logs for the reason.
+
+**iOS: push works in development but not from TestFlight (or the reverse)**
+Set the APNs environment of the app to `auto` in the dashboard. The SDK sends `test_type = 1` for development-signed builds, so the server uses the sandbox gateway for them.
+
+**iOS: no image, no buttons, or delivery not confirmed**
+These depend on the Notification Service Extension. Check that:
+- the extension target exists and is embedded in the app (Build Phases > Embed Foundation Extensions / Copy Files)
+- its deployment target is not higher than the device's iOS version
+- both targets have the **same App Group**. Open the app once after installing so it writes its config to the group.
+- the server sends `mutable-content: 1` (QPush always does)
+
+**iOS: foreground notifications not shown, or taps not reported, with another notification library**
+QPush keeps itself as the `UNUserNotificationCenter` delegate and forwards non-QPush notifications to the delegate set by the other library. If a library overrides delegate methods through swizzling, initialize QPush first and check the order in which the libraries are linked.
+
+**Clicks that open the app are missing**
+Add the `click` listener early, at module scope or in your root component. Clicks are queued natively until JS is ready, and in JS until the first listener is added.
+
+**Nothing is sent**
+- `setConsentRequired(true)` without `setConsentGiven(true)` blocks all network traffic.
+- If `android_params.js` / `ios_params.js` returns `404`, the app id or `serverUrl` is wrong, and the SDK stops syncing until the next launch. Look for "was not found" in the logs.
+
+---
+
+## Developing against a plain-HTTP server
+
+Production servers should use HTTPS. While developing against a QPush server on
+your LAN (for example `http://192.168.1.10:8080`):
+
+- **Android:** delivery receipts and click reports are sent by native code,
+  which Android blocks over cleartext HTTP. Allow it in debug builds only:
+  `<application android:usesCleartextTraffic="true"/>` in
+  `android/app/src/debug/AndroidManifest.xml` (React Native debug builds already allow it).
+- **iOS:** IP addresses are exempt from App Transport Security. For `.local`
+  hostnames (`http://my-mac.local:8080`) add `NSAppTransportSecurity →
+  NSAllowsLocalNetworking = YES` to the app's and the Notification Service
+  Extension's `Info.plist`. The Expo plugin adds it automatically when `mode` is `"development"`, and the shipped NSE template includes it.
+
+The SDK logs a warning at startup when `serverUrl` uses plain HTTP.
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,77 @@
+buildscript {
+  ext.qpushSafeExtGet = { name, fallback ->
+    rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["QPushPush_" + name] ?: fallback)
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.2.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${qpushSafeExtGet('kotlinVersion', '1.9.24')}"
+  }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+def safeExtGetInt(name, fallback) {
+  def value = rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["QPushPush_" + name]
+  return value != null ? value.toString().toInteger() : fallback
+}
+
+def appMinSdk = safeExtGetInt("minSdkVersion", 21)
+
+// Firebase BoM 33.x supports minSdk 21. Apps can pick a newer BoM (34.x needs
+// minSdk 23+) with `ext.qpushFirebaseBomVersion = "34.x.y"` in the root
+// build.gradle. If the app already uses Firebase, Gradle resolves the highest
+// firebase-messaging version anyway.
+def firebaseBomVersion = rootProject.ext.has("qpushFirebaseBomVersion") ?
+    rootProject.ext.get("qpushFirebaseBomVersion") :
+    (project.properties["QPushPush_firebaseBomVersion"] ?: "33.16.0")
+
+android {
+  if (project.android.hasProperty("namespace")) {
+    namespace "com.qpush.reactnative"
+  }
+
+  compileSdkVersion safeExtGetInt("compileSdkVersion", 34)
+
+  defaultConfig {
+    minSdkVersion appMinSdk
+    targetSdkVersion safeExtGetInt("targetSdkVersion", 34)
+    consumerProguardFiles "proguard-rules.pro"
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+def kotlinVersion = qpushSafeExtGet("kotlinVersion", "1.9.24")
+
+dependencies {
+  // Version provided by the React Native Gradle plugin of the app.
+  implementation "com.facebook.react:react-android"
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:${kotlinVersion}"
+
+  implementation platform("com.google.firebase:firebase-bom:${firebaseBomVersion}")
+  implementation "com.google.firebase:firebase-messaging"
+
+  implementation "androidx.core:core:1.9.0"
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+QPushPush_kotlinVersion=1.9.24
+QPushPush_minSdkVersion=21
+QPushPush_targetSdkVersion=34
+QPushPush_compileSdkVersion=34
+QPushPush_firebaseBomVersion=33.16.0

package/android/proguard-rules.pro

@@ -0,0 +1,5 @@
+# Keep the classes referenced from the manifest and by React Native reflection.
+-keep class com.qpush.reactnative.QPushMessagingService { *; }
+-keep class com.qpush.reactnative.QPushNotificationOpenActivity { *; }
+-keep class com.qpush.reactnative.QPushPushModule { *; }
+-keep class com.qpush.reactnative.QPushPushPackage { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,29 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+  <uses-permission android:name="android.permission.VIBRATE" />
+  <!-- Android 13+ runtime notification permission. -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+  <application>
+    <!-- Receives QPush data messages (data["qpush"]) and renders them. -->
+    <service
+      android:name="com.qpush.reactnative.QPushMessagingService"
+      android:exported="false">
+      <intent-filter>
+        <action android:name="com.google.firebase.MESSAGING_EVENT" />
+      </intent-filter>
+    </service>
+
+    <!-- Transparent trampoline started directly by the notification PendingIntent
+         (Android 12+ compliant: no service/receiver trampolines). -->
+    <activity
+      android:name="com.qpush.reactnative.QPushNotificationOpenActivity"
+      android:excludeFromRecents="true"
+      android:exported="false"
+      android:noHistory="true"
+      android:taskAffinity=""
+      android:theme="@android:style/Theme.Translucent.NoTitleBar" />
+  </application>
+</manifest>

package/android/src/main/java/com/qpush/reactnative/QPushDeviceInfo.kt

@@ -0,0 +1,96 @@
+package com.qpush.reactnative
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.NetworkCapabilities
+import android.os.Build
+import android.telephony.TelephonyManager
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import java.io.File
+import java.util.Locale
+import java.util.TimeZone
+
+/** Device fields sent with the subscription (see SubscriptionPayload in the protocol). */
+internal object QPushDeviceInfo {
+  fun collect(context: Context): WritableMap {
+    val map = Arguments.createMap()
+    val locale = Locale.getDefault()
+    map.putString("platform", "android")
+    map.putString("deviceModel", Build.MODEL)
+    map.putString("deviceOs", Build.VERSION.RELEASE)
+    appVersion(context)?.let { map.putString("appVersion", it) }
+    map.putString("timezone", TimeZone.getDefault().id)
+    val tag = locale.toLanguageTag()
+    map.putString("locale", tag)
+    // toLanguageTag() maps legacy codes (iw -> he, in -> id).
+    map.putString("language", tag.substringBefore('-').lowercase(Locale.ROOT))
+    if (locale.country.isNotEmpty()) map.putString("country", locale.country)
+    carrier(context)?.let { map.putString("carrier", it) }
+    map.putBoolean("rooted", isRooted())
+    netType(context)?.let { map.putInt("netType", it) }
+    return map
+  }
+
+  @Suppress("DEPRECATION")
+  private fun appVersion(context: Context): String? = try {
+    context.packageManager.getPackageInfo(context.packageName, 0).versionName
+  } catch (e: Exception) {
+    null
+  }
+
+  private fun carrier(context: Context): String? = try {
+    val telephony = context.getSystemService(Context.TELEPHONY_SERVICE) as? TelephonyManager
+    telephony?.networkOperatorName?.takeIf { it.isNotBlank() }
+  } catch (e: Exception) {
+    null
+  }
+
+  /** 0 wifi/ethernet, 1 cellular, null unknown. Needs ACCESS_NETWORK_STATE. */
+  @Suppress("DEPRECATION")
+  private fun netType(context: Context): Int? = try {
+    val connectivity = context.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+    if (connectivity == null) {
+      null
+    } else if (Build.VERSION.SDK_INT >= 23) {
+      val capabilities = connectivity.getNetworkCapabilities(connectivity.activeNetwork)
+      when {
+        capabilities == null -> null
+        capabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI) ||
+          capabilities.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET) -> 0
+        capabilities.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR) -> 1
+        else -> null
+      }
+    } else {
+      when (connectivity.activeNetworkInfo?.type) {
+        ConnectivityManager.TYPE_WIFI, ConnectivityManager.TYPE_ETHERNET -> 0
+        ConnectivityManager.TYPE_MOBILE -> 1
+        else -> null
+      }
+    }
+  } catch (e: Exception) {
+    null
+  }
+
+  private fun isRooted(): Boolean {
+    if (Build.TAGS?.contains("test-keys") == true) return true
+    val paths = arrayOf(
+      "/system/app/Superuser.apk",
+      "/sbin/su",
+      "/system/bin/su",
+      "/system/xbin/su",
+      "/data/local/xbin/su",
+      "/data/local/bin/su",
+      "/system/sd/xbin/su",
+      "/system/bin/failsafe/su",
+      "/data/local/su",
+    )
+    return paths.any { path ->
+      try {
+        File(path).exists()
+      } catch (e: Exception) {
+        false
+      }
+    }
+  }
+}