docs(notifications): document debug panel auth settings and bypassAuth
Add doc/notification-debug-panel.md as the canonical panel reference. Update ngrok guides, README, and analysis doc to describe independent Backend URL, Test Mode, and Skip JWT Authentication settings, including recommended configs for hosted test servers vs local ngrok.
This commit is contained in:
Jose Olarte III
@@ -277,6 +277,8 @@ Before ngrok end-to-end testing, confirm:
|
||||
|
||||
The app normally calls `APP_SERVER` (from `VITE_APP_SERVER`). For local wakeup testing, override the notification API base URL without rebuilding.
|
||||
|
||||
For a full panel reference (configuration, authentication, and troubleshooting), see [notification-debug-panel.md](./notification-debug-panel.md).
|
||||
|
||||
### Open the panel
|
||||
|
||||
1. Use a **non-production** build (e.g. `build:android:dev` or `build:android:test`).
|
||||
@@ -287,15 +289,28 @@ The app normally calls `APP_SERVER` (from `VITE_APP_SERVER`). For local wakeup t
|
||||
|
||||
| Control | Purpose |
|
||||
|---------|---------|
|
||||
| **Notification Backend URL** | Paste ngrok HTTPS URL → **Save Backend URL** |
|
||||
| **Test Mode** | Sends `testMode: true` on register/refresh (default on when unset in storage) |
|
||||
| **Notification Backend URL** | Paste ngrok HTTPS URL → **Save Backend URL** (changes target server only) |
|
||||
| **Test Mode** | Sends `testMode: true/false` in register/refresh JSON bodies (default on when unset in storage) |
|
||||
| **Skip JWT Authentication (Local Development Only)** | When on, omits `Authorization` headers for local servers that accept unauthenticated requests (default **off**) |
|
||||
| **Register Token Now** | `POST /notifications/register` with current FCM token and `platform: "android"` |
|
||||
| **Refresh Notifications** | `POST /notifications/refresh` (same as post-wakeup flow) |
|
||||
| **Simulate WAKEUP_PING (Local)** | Calls refresh API directly (no FCM) — quick backend + ngrok test |
|
||||
| **Send Real WAKEUP_PING** | `POST /debug/send-wakeup` on the backend override URL; server sends a real FCM `WAKEUP_PING` to the panel’s current FCM token (see below) |
|
||||
| **Event Log** | Shared `[Notifications]` panel log (100 entries) |
|
||||
|
||||
Persistence: `localStorage` keys `notificationDebug.backendBaseUrl` and `notificationDebug.testMode` (`NotificationDebugConfig.ts`).
|
||||
Persistence: `localStorage` keys `notificationDebug.backendBaseUrl`, `notificationDebug.testMode`, and `notificationDebug.bypassAuth` (`NotificationDebugConfig.ts`).
|
||||
|
||||
### Authentication vs backend URL
|
||||
|
||||
These settings are **independent**:
|
||||
|
||||
- **Backend URL** — which server receives `/notifications/*` and `/debug/*` calls.
|
||||
- **Test Mode** — `testMode` field in JSON request bodies only.
|
||||
- **Skip JWT Authentication** — whether `Authorization: Bearer …` is sent (via `getNotificationApiHeaders()`).
|
||||
|
||||
For a **hosted shared test server** (for example `https://test-notify-api.timesafari.app`): set the backend URL, keep **Test Mode** on if the server requires it, and leave **Skip JWT Authentication** **off**. Ensure an active DID and endorser session exist in the app.
|
||||
|
||||
For **local ngrok / localhost**: set the backend URL to your tunnel or `http://127.0.0.1:PORT`. Enable **Skip JWT Authentication** only if your local **notification-wakeup-service** intentionally accepts unauthenticated requests.
|
||||
|
||||
### testMode
|
||||
|
||||
@@ -347,7 +362,7 @@ On a **successful end-to-end** run (HTTP success from the panel, then FCM delive
|
||||
[Notifications] Refresh completed (WAKEUP_PING) in …ms (scheduled N)
|
||||
```
|
||||
|
||||
Intermediate lines (e.g. `WAKEUP_PING received — will trigger refresh`, `Schedule replacement: …`, auth bypass messages) are normal. ngrok should also show a new `POST /notifications/refresh` after the push is handled.
|
||||
Intermediate lines (e.g. `WAKEUP_PING received — will trigger refresh`, `Schedule replacement: …`, `Using authenticated notification request` or auth bypass messages when **Skip JWT Authentication** is on) are normal. ngrok should also show a new `POST /notifications/refresh` after the push is handled.
|
||||
|
||||
#### Send Real WAKEUP_PING vs end-to-end success
|
||||
|
||||
@@ -363,11 +378,13 @@ From Chrome DevTools attached to the WebView (`chrome://inspect` → your app):
|
||||
import {
|
||||
setBackendBaseUrl,
|
||||
setTestMode,
|
||||
setBypassAuth,
|
||||
getNotificationApiBaseUrl,
|
||||
} from "@/services/notifications";
|
||||
|
||||
setBackendBaseUrl("https://abc123.ngrok-free.app");
|
||||
setTestMode(true);
|
||||
setBypassAuth(true); // local dev only — omit for hosted servers that require JWT
|
||||
getNotificationApiBaseUrl(); // → ngrok URL
|
||||
```
|
||||
|
||||
@@ -509,7 +526,7 @@ If wakeup works on a **Pixel** but fails on an OEM phone, assume battery policy
|
||||
2. Start **ngrok** and copy the HTTPS URL.
|
||||
3. Install a **non-production** Android build with `google-services.json` in place.
|
||||
4. Grant notification permission when prompted (or enable in Settings).
|
||||
5. Open **Notification Debug Panel** → paste ngrok URL → **Save Backend URL**; confirm **Test Mode** is on.
|
||||
5. Open **Notification Debug Panel** → paste ngrok URL → **Save Backend URL**; confirm **Test Mode** is on; enable **Skip JWT Authentication** only if your local backend accepts unauthenticated requests.
|
||||
6. Tap **Register Token Now** → confirm ngrok `POST /notifications/register` and `[Notifications] Token registration success` in Event Log / logcat.
|
||||
7. Tap **Refresh Notifications** → confirm `POST /notifications/refresh` and `Refresh completed in Nms (scheduled X)` in Event Log.
|
||||
8. Optional: tap **Simulate WAKEUP_PING (Local)** to verify ngrok + refresh without FCM.
|
||||
@@ -837,7 +854,7 @@ Structured checks for local ngrok + FCM testing. Each item lists **symptoms**, *
|
||||
|
||||
**Symptoms:** Event Log shows token registration failure; no FCM token in debug panel; ngrok has no `POST /notifications/register`; curl register fails.
|
||||
|
||||
**Likely causes:** Notification permission denied; missing `google-services.json`; Firebase package mismatch (`app.timesafari.app`); `VITE_FIREBASE_*` not in build; auth headers missing for register; duplicate-token skip.
|
||||
**Likely causes:** Notification permission denied; missing `google-services.json`; Firebase package mismatch (`app.timesafari.app`); `VITE_FIREBASE_*` not in build; JWT auth failure or **Skip JWT Authentication** mismatch with server expectations; duplicate-token skip.
|
||||
|
||||
**Verification:**
|
||||
|
||||
@@ -846,7 +863,7 @@ Structured checks for local ngrok + FCM testing. Each item lists **symptoms**, *
|
||||
3. Panel shows a token string before **Register Token Now**.
|
||||
4. ngrok inspect UI (`http://127.0.0.1:4040`) for register request status body.
|
||||
|
||||
**Fixes:** Grant permission and cold-start app; add `android/app/google-services.json` and rebuild; align Firebase Android app ID with Gradle `applicationId`; rebuild with correct `.env`; tap **Register Token Now** (forces re-register); fix DID/auth if register returns 401.
|
||||
**Fixes:** Grant permission and cold-start app; add `android/app/google-services.json` and rebuild; align Firebase Android app ID with Gradle `applicationId`; rebuild with correct `.env`; tap **Register Token Now** (forces re-register); for JWT-required servers, ensure active DID/endorser session and **Skip JWT Authentication** off; for local unauthenticated backends, enable **Skip JWT Authentication** (see [notification-debug-panel.md](./notification-debug-panel.md)).
|
||||
|
||||
---
|
||||
|
||||
@@ -985,7 +1002,7 @@ Compare with panel **Backend Status** and Event Log error text.
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `src/services/notifications/NotificationDebugConfig.ts` | Backend URL + testMode override |
|
||||
| `src/services/notifications/NotificationDebugConfig.ts` | Backend URL, testMode, and bypassAuth overrides |
|
||||
| `src/services/notifications/NotificationDebugEvents.ts` | Panel event log + `logNotification()` |
|
||||
| `src/services/notifications/notificationLog.ts` | Structured log helpers |
|
||||
| `src/services/notifications/NotificationService.ts` | `POST /notifications/register` |
|
||||
@@ -1007,6 +1024,7 @@ Compare with panel **Backend Status** and Event Log error text.
|
||||
- [notification-from-api-call.md](./notification-from-api-call.md)
|
||||
- [notification-permissions-and-rollovers.md](./notification-permissions-and-rollovers.md)
|
||||
- [BUILDING.md](../BUILDING.md) — Android build commands
|
||||
- [notification-debug-panel.md](./notification-debug-panel.md) — panel controls, authentication, troubleshooting
|
||||
- [Notification Debug Panel (README)](../README.md#notification-debug-panel-dev-builds)
|
||||
|
||||
For plugin-native behavior (exact alarms, Android pending inspector), see **daily-notification-plugin** documentation. For FCM payload format and `/debug/send-wakeup` contract, see **notification-wakeup-service**.
|
||||
|
||||
Reference in New Issue
Block a user