capacitor-push-signal 0.0.3 → 0.0.4

package/README.md

@@ -111,6 +111,53 @@ Without `initialize(...)` or that file, `getCredentials()` throws.
 
 If the host app already declares its own `FirebaseMessagingService`, only one service can handle `com.google.firebase.MESSAGING_EVENT`. Prefer this plugin’s service or forward events into it.
 
+### Detecting a non-Google device: `getDiagnostics()` and `PushSignalError`
+
+When Google Play services cannot serve FCM, the plugin detects it and tells you which service to use instead — both in the error message and as structured data, so the cause is visible in JS logs. Before requesting a token it checks Google Play services and retries up to 5 times with backoff and a 10 s per-attempt timeout.
+
+`initialize()` and `getCredentials()` reject with `PushSignalError`:
+
+```ts
+import { getCredentials, PushSignalError } from 'capacitor-push-signal';
+
+try {
+  const credentials = await getCredentials();
+} catch (error) {
+  if (error instanceof PushSignalError) {
+    console.warn(error.code); // E_GMS_MISSING, E_FCM_TOKEN, ...
+    console.warn(error.message); // "... Use HMS Push Kit (Huawei Push) instead of the standard Google service."
+    console.warn(error.provider); // 'hms'
+    console.warn(error.hint); // actionable sentence
+    console.warn(error.diagnostics); // full device/provider snapshot
+  }
+}
+```
+
+You can also inspect diagnostics without requesting a token:
+
+```ts
+import { getDiagnostics } from 'capacitor-push-signal';
+
+const diagnostics = await getDiagnostics();
+// { platform, gmsAvailable, gmsStatus, manufacturer, brand, model,
+//   provider, providerName, providerInstalled?, hint? }
+```
+
+Provider suggested when GMS is unavailable:
+
+| Manufacturer            | `provider`   | Service                        |
+| ----------------------- | ------------ | ------------------------------ |
+| HUAWEI / HONOR          | `hms`        | HMS Push Kit (Huawei Push)     |
+| Xiaomi / Redmi / POCO   | `mi_push`    | Mi Push (Xiaomi Push)          |
+| OPPO / OnePlus / realme | `oppo_push`  | OPPO Push (HeyTap)             |
+| vivo / iQOO             | `vivo_push`  | vivo Push                      |
+| Meizu                   | `meizu_push` | Meizu Push                     |
+| anything else           | `unknown`    | generic “use another provider” |
+
+`providerInstalled` is `true` only when the provider service app was positively found on the device (`com.huawei.hwid`, `com.xiaomi.xmsf`); otherwise it is omitted. iOS always reports `provider: 'apns'`. The plugin never logs for you — pass the data wherever you need.
+
+Error codes: `E_GMS_MISSING`, `E_GMS_DISABLED`, `E_GMS_UPDATE_REQUIRED`, `E_GMS_INVALID`, `E_GMS_UNAVAILABLE`, `E_FCM_TOKEN`, `E_FIREBASE_CONFIG`, `E_NOT_INITIALIZED`, `E_CREDENTIALS`, `E_INIT`, `E_DIAGNOSTICS`.
+
 ## Incoming messages vs taps
 
 | App state | iOS | Android (notification payload) | Android (data-only) |
@@ -122,6 +169,66 @@ If the host app already declares its own `FirebaseMessagingService`, only one se
 - `onNotificationPress` — the user opened the notification, including a cold start.
 - On iOS, a visible push received in the background or when the app is killed is delivered on tap, not through `onMessage`. That is an OS limit.
 
+## Rich / image notifications
+
+`PushMessage.imageUrl` is resolved from (first match wins):
+
+1. FCM `notification.image` / `RemoteMessage.notification.imageUrl` (Android)
+2. `data.image`
+3. `data.imageUrl`
+4. iOS also: `fcm_options.image` (FCM → APNs)
+
+| App state | iOS | Android |
+| --- | --- | --- |
+| Foreground | Needs a host **Notification Service Extension** (NSE) to attach the image; the plugin forwards `imageUrl` to JS | Plugin downloads the image and shows `BigPictureStyle` in the tray |
+| Background / killed | NSE attaches the image when `mutable-content: 1` is set | FCM system tray usually shows `notification.image` without plugin code |
+
+### Android payload (FCM HTTP v1)
+
+Put the image on both `notification` (background tray) and `data` (foreground path / JS):
+
+```json
+{
+  "message": {
+    "token": "...",
+    "notification": {
+      "title": "Hello",
+      "body": "With image",
+      "image": "https://example.com/photo.jpg"
+    },
+    "data": {
+      "image": "https://example.com/photo.jpg"
+    }
+  }
+}
+```
+
+### iOS payload (APNs)
+
+```json
+{
+  "aps": {
+    "alert": { "title": "Hello", "body": "With image" },
+    "mutable-content": 1,
+    "sound": "default"
+  },
+  "image": "https://example.com/photo.jpg"
+}
+```
+
+### iOS Notification Service Extension
+
+iOS never downloads remote images for you. Add an NSE to the **host** Capacitor app (not installed by `npx cap sync`).
+
+1. Xcode → **File → New → Target → Notification Service Extension**.
+2. Copy [`example-app/ios/App/NotificationService/NotificationService.swift`](example-app/ios/App/NotificationService/NotificationService.swift) into the extension (see also that folder’s README).
+3. Keep the extension bundle id under your app id (e.g. `com.example.app.NotificationService`).
+4. Send pushes with `mutable-content: 1` and `image` / `imageUrl`.
+
+The example app already wires a **NotificationService** target for reference.
+
+If image download fails, both platforms fall back to a normal title/body notification.
+
 ## Web
 
 `initialize()` resolves. `getCredentials()` throws. Listeners (`onMessage`, `onNotificationPress`) are no-ops.
@@ -132,6 +239,7 @@ If the host app already declares its own `FirebaseMessagingService`, only one se
 
 * [`initialize(...)`](#initialize)
 * [`getCredentials()`](#getcredentials)
+* [`getDiagnostics()`](#getdiagnostics)
 * [`checkPermissions()`](#checkpermissions)
 * [`requestPermissions()`](#requestpermissions)
 * [`startListening()`](#startlistening)
@@ -173,6 +281,23 @@ Returns APNs (iOS) or FCM (Android) credentials for your server.
 --------------------
 
 
+### getDiagnostics()
+
+```typescript
+getDiagnostics() => Promise<PushDiagnostics>
+```
+
+Inspect the device push provider without requesting a token.
+
+On Android it reports whether Google Play services can serve FCM and, when
+they cannot, which service to use instead (HMS, Mi Push, OPPO/vivo/Meizu).
+On iOS it always reports APNs.
+
+**Returns:** <code>Promise&lt;<a href="#pushdiagnostics">PushDiagnostics</a>&gt;</code>
+
+--------------------
+
+
 ### checkPermissions()
 
 ```typescript
@@ -265,11 +390,26 @@ addListener(eventName: 'onNotificationPress', listenerFunc: (message: PushMessag
 
 | Prop              | Type                                                        |
 | ----------------- | ----------------------------------------------------------- |
-| **`platform`**    | <code><a href="#pushplatform">PushPlatform</a></code>       |
 | **`token`**       | <code>string</code>                                         |
 | **`environment`** | <code><a href="#pushenvironment">PushEnvironment</a></code> |
 
 
+#### PushDiagnostics
+
+| Prop                    | Type                                                  | Description                                                                      |
+| ----------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| **`platform`**          | <code><a href="#pushplatform">PushPlatform</a></code> |                                                                                  |
+| **`gmsAvailable`**      | <code>boolean</code>                                  | True when Google Play services can serve FCM; false on a ROM without GMS.        |
+| **`gmsStatus`**         | <code>number</code>                                   | Raw GoogleApiAvailability status code. 0 means SUCCESS.                          |
+| **`manufacturer`**      | <code>string</code>                                   |                                                                                  |
+| **`brand`**             | <code>string</code>                                   |                                                                                  |
+| **`model`**             | <code>string</code>                                   |                                                                                  |
+| **`provider`**          | <code><a href="#pushprovider">PushProvider</a></code> |                                                                                  |
+| **`providerName`**      | <code>string</code>                                   | Human-readable provider name, e.g. "HMS Push Kit".                               |
+| **`providerInstalled`** | <code>boolean</code>                                  | True only when the provider service app was positively found on the device.      |
+| **`hint`**              | <code>string</code>                                   | Actionable sentence explaining which service to use instead of the standard one. |
+
+
 #### PermissionStatus
 
 | Prop          | Type                                                        |
@@ -286,25 +426,31 @@ addListener(eventName: 'onNotificationPress', listenerFunc: (message: PushMessag
 
 #### PushMessage
 
-| Prop        | Type                                                            |
-| ----------- | --------------------------------------------------------------- |
-| **`id`**    | <code>string</code>                                             |
-| **`title`** | <code>string</code>                                             |
-| **`body`**  | <code>string</code>                                             |
-| **`data`**  | <code><a href="#record">Record</a>&lt;string, string&gt;</code> |
+| Prop           | Type                                                            | Description                                                                  |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **`id`**       | <code>string</code>                                             |                                                                              |
+| **`title`**    | <code>string</code>                                             |                                                                              |
+| **`body`**     | <code>string</code>                                             |                                                                              |
+| **`imageUrl`** | <code>string</code>                                             | Resolved image URL from FCM notification.image / data.image / data.imageUrl. |
+| **`data`**     | <code><a href="#record">Record</a>&lt;string, string&gt;</code> |                                                                              |
 
 
 ### Type Aliases
 
 
+#### PushEnvironment
+
+<code>'sandbox' | 'production'</code>
+
+
 #### PushPlatform
 
 <code>'ios' | 'android'</code>
 
 
-#### PushEnvironment
+#### PushProvider
 
-<code>'sandbox' | 'production'</code>
+<code>'fcm' | 'hms' | 'mi_push' | 'oppo_push' | 'vivo_push' | 'meizu_push' | 'apns' | 'unknown'</code>
 
 
 #### PermissionState

package/android/build.gradle

@@ -59,6 +59,7 @@ dependencies {
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation "androidx.activity:activity-ktx:1.10.1"
     implementation "androidx.core:core-ktx:1.16.0"
+    implementation "com.google.android.gms:play-services-base:18.5.0"
     implementation "com.google.firebase:firebase-messaging:24.1.2"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"

package/android/src/main/AndroidManifest.xml

@@ -1,7 +1,15 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
+    <!-- Android 11+ package visibility: lets isPackageInstalled() confirm an
+         alternative push provider on the device. -->
+    <queries>
+        <package android:name="com.huawei.hwid" />
+        <package android:name="com.xiaomi.xmsf" />
+    </queries>
+
     <application>
         <provider
             android:name="com.antonseagull.cap.push.signal.PushSignalInitProvider"

package/android/src/main/java/com/antonseagull/cap/push/signal/PushModels.kt

@@ -5,6 +5,7 @@ data class PushMessage(
   val title: String?,
   val body: String?,
   val data: Map<String, String>,
+  val imageUrl: String? = null,
 )
 
 data class AndroidFirebaseConfig(
@@ -13,3 +14,26 @@ data class AndroidFirebaseConfig(
   val current_key: String?,
   val project_number: String?,
 )
+
+data class PushDiagnostics(
+  val platform: String,
+  val gmsAvailable: Boolean,
+  val gmsStatus: Int,
+  val manufacturer: String,
+  val brand: String,
+  val model: String,
+  val provider: String,
+  val providerName: String,
+  val providerInstalled: Boolean?,
+  val hint: String?,
+)
+
+/**
+ * Carries a machine-readable [code] to JavaScript, so the host app can branch on
+ * the exact reason (missing GMS, disabled GMS, FCM token failure, ...).
+ */
+class PushSignalException(
+  val code: String,
+  message: String,
+  cause: Throwable? = null,
+) : IllegalStateException(message, cause)