crowd-funder-for-time-pwa/doc/local-android-testing-analysis.md

Android Local Notification Testing — Planning Analysis

Created: 2026-06-02
Source document: local-ios-testing-ngrok.md
Purpose: Plan a future Android counterpart guide by mapping what can be reused from the iOS ngrok workflow and what must be written for Android-specific push, permissions, and OS behavior.

Status: Planning only — does not replace or modify the iOS guide.

---

Executive summary

The iOS guide’s backend + ngrok + in-app debug panel path is platform-agnostic. Most of sections 1–3, 6, 9 (with log tooling swapped), 10 (with platform: "android"), 12, and parts of 11 can be copied or lightly edited.

Everything involving APNs, Xcode, Apple Developer, iOS capabilities, and iOS background/silent-push caveats must be replaced. Android adds direct FCM delivery (no APNs hop), google-services.json, runtime notification permissions (API 33+), Doze / battery optimization / OEM restrictions, and different force-stop / background semantics.

Existing related docs to cross-link (not duplicate):

• android-physical-device-guide.md — USB, adb, build/run commands
• notification-system-overview.md
• notification-from-api-call.md
• notification-permissions-and-rollovers.md

---

iOS guide structure (reference map)

§	iOS doc heading	Reuse for Android
Intro	Architecture overview	Adapt — swap APNs leg for FCM→device
—	Prerequisites	Partial — drop Xcode/APNs; add Android SDK/device
1	Install and configure ngrok	Reuse unchanged
2	Start the backend locally	Reuse unchanged
3	Obtain and use ngrok HTTPS URL	Reuse — wording: “device” not “iPhone”
4	Generate and open iOS workspace	Rewrite — Android Studio / Capacitor sync
5	Firebase + APNs setup	Rewrite — Firebase Android only; no APNs
6	Notification Debug Panel override	Reuse unchanged
7	Firebase and Xcode checklist	Rewrite — Android manifest / Gradle checklist
8	iOS-specific testing notes	Rewrite — Android delivery caveats
9	Recommended debug workflow	Reuse — replace Xcode console with logcat
10	Sample curl commands	Reuse — change platform to android
11	Troubleshooting	Partial — keep ngrok/API rows; replace push rows
12	Key source files	Reuse unchanged
13	Related docs	Extend — link Android build/device guides

---

Sections reusable unchanged (or near-unchanged)

These blocks can be carried into doc/local-android-testing-ngrok.md (proposed name) with at most global find-replace (“iPhone” → “Android device”, “Mac” tunnel audience unchanged).

notification-wakeup-service startup (iOS §1 Terminal A, §2)

• Clone notification-wakeup-service, npm install, .env from .env.example
• export PORT=3000 (or port from that repo’s README)
• npm run dev
• Local verify: curl -sS http://localhost:3000/health
• Firebase Admin service account for the backend (GOOGLE_APPLICATION_CREDENTIALS) — same project can serve iOS and Android apps

ngrok setup (iOS §1)

• brew install ngrok/ngrok/ngrok (or download)
• ngrok http 3000 in a second terminal
• Use HTTPS forwarding URL; free tier URL rotation note
• ngrok inspect UI at http://127.0.0.1:4040

ngrok account creation (iOS §1 “Account and auth token”)

• Sign up at dashboard.ngrok.com
• ngrok config add-authtoken YOUR_AUTHTOKEN_HERE

Obtaining HTTPS URL (iOS §3)

• Copy https://….ngrok-free.app from Forwarding line
• No trailing slash in debug panel
• Mac-side tunnel test: export NGROK_URL=… and curl "$NGROK_URL/health"

Backend override configuration (iOS §6)

• Non-production build required for Notification Debug Panel
• Account → Show All General Advanced Functions → /dev/notifications
• Notification Backend URL, Save Backend URL
• localStorage: notificationDebug.backendBaseUrl, notificationDebug.testMode
• Optional programmatic override via @/services/notifications (setBackendBaseUrl, setTestMode, getNotificationApiBaseUrl)

Debug panel usage (iOS §6 table, §8 “Two Simulate WAKEUP_PING buttons”)

Control	Android relevance
Notification Backend URL	Same
Test Mode	Same (testMode: true on API)
Register Token Now	Same (POST /notifications/register)
Refresh Notifications	Same
Simulate WAKEUP_PING (backend)	Same — isolates ngrok + refresh without FCM
Wakeup Ping Simulator	Same — exercises handleCapacitorPushNotificationReceived path
Event Log [Notifications]	Same
Pending Notification Inspector	Same concept; confirm Android plugin inspector behavior in daily-notification-plugin

testMode usage (iOS §6, §10)

• Default-on when unset in storage (NotificationDebugConfig.ts)
• Sent on register and refresh payloads
• Backend/debug endpoints accept testMode: true for dev traffic

Refresh endpoint testing (iOS §9 steps 5, §11 “Refresh endpoint unreachable”)

• Panel Refresh Notifications → expect Event Log + ngrok POST /notifications/refresh
• Simulate WAKEUP_PING (backend button) for API-only path
• Troubleshooting table for network error, 404, wrong port, stale URL

curl examples (iOS §10)

Reuse structure; only payload deltas for Android doc:

export BASE="https://abc123.ngrok-free.app"

• $BASE/health — unchanged
• $BASE/notifications/register — set "platform": "android"
• $BASE/notifications/refresh — set "platform": "android"
• $BASE/debug/send-wakeup — unchanged shape; confirm deviceId/token contract in notification-wakeup-service README

App still uses Capacitor.getPlatform() for platform in NotificationService.ts (ios | android).

Shared architecture concepts (intro + silent wake sequence)

Reusable narrative (edit diagram only):

1. FCM data message with data.type = "WAKEUP_PING"
2. Capacitor pushNotificationReceived → handleCapacitorPushNotificationReceived()
3. POST {backend}/notifications/refresh with testMode
4. nextNotifications → applyNotificationRefreshPayload() → daily-notification-plugin clear + schedule

Repos table (notification-wakeup-service, crowd-funder-for-time-pwa, daily-notification-plugin) — unchanged.

Key source files (iOS §12)

Same files apply on Android Capacitor builds:

• NotificationDebugConfig.ts, NotificationDebugEvents.ts, notificationLog.ts
• NotificationService.ts, NativeNotificationService.ts
• firebaseMessagingClient.ts, NotificationDebugPanel.vue, main.capacitor.ts

Recommended debug workflow (iOS §9) — reuse with tooling swap

Steps 1–5, 8–9 unchanged. Replace step 7:

• iOS: Xcode console → [Notifications] pushNotificationReceived type=WAKEUP_PING
• Android: adb logcat filtered on app tag / [Notifications] (document exact filter in Android guide)

---

iOS-specific sections — must rewrite for Android

Architecture diagram (intro)

iOS today: Mac → ngrok → app; FCM → APNs → iPhone.

Android doc: FCM → device directly (no APNs). Update ASCII diagram and caption (“silent push” on Android is still FCM data; delivery rules differ).

Prerequisites (intro list)

iOS prerequisite	Android replacement
Mac with Xcode	Android Studio, JDK 17+, ANDROID_HOME, adb — see android-physical-device-guide.md
Physical iPhone	Physical Android device (emulator possible for some steps but not representative for Doze/OEM/battery)
Firebase with APNs for bundle ID	Firebase with Android app (app.timesafari package name)
Non-production build	Same — e.g. build:android:dev / build:android:test

Remove: “simulator is not sufficient for reliable silent push / APNs”.

Add: emulator vs physical device guidance for FCM and background limits.

§4 — Generate and open the iOS workspace

Replace entirely with Android equivalent:

• npm install
• npm run build:android:dev or build:android:test (non-production for debug panel)
• npx cap sync android if needed
• Open android/ in Android Studio
• Run on physical device (USB debugging)
• VITE_FIREBASE_* in Capacitor web build
• initializeNativePushAndFirebaseMessaging() in main.capacitor.ts — same entry point

Do not reference .xcworkspace, signing in Xcode, or build:ios:* except as cross-link to iOS doc.

§5 — Firebase + APNs setup (first-time setup)

Keep (Android-relevant portions only):

• Firebase account / Spark plan sufficient for FCM
• Create Firebase project
• Register Android app in Firebase (package name app.timesafari from capacitor.config.ts)
• Download google-services.json → android/app/ (project may gitignore this file — document secure handling)
• Firebase Admin service account for notification-wakeup-service — same as iOS §5 tail

Remove entirely:

• Register iOS app in Firebase (or move to “shared project” sidebar: one Firebase project, two apps)
• GoogleService-Info.plist / Xcode drag-and-drop
• Create APNs Authentication Key (.p8)
• Upload APNs key to Firebase
• Enable iOS capabilities (Push Notifications, Background Modes → Remote notifications)

Add in Android guide (see next major section):

• Gradle plugin / google-services classpath if not already in repo
• POST_NOTIFICATIONS permission (API 33+)
• Default notification channel / Capacitor Push Notifications Android setup
• SHA-1/SHA-256 only if using Firebase features that require it (note whether wakeup testing needs Play App Signing keys)

§5 verify checklist — iOS-only bullets

Replace:

• “Xcode without Firebase/plist errors” → Android Studio build; google-services.json present
• “iOS push permission prompt” → Android 13+ notification permission + older grant model
• “content-available style payload” → Android high-priority data message / FCM options as implemented by notification-wakeup-service (document actual payload; no APNs content-available)

§7 — Firebase and Xcode checklist (iOS)

Replace with Android checklist, e.g.:

Item	Action
Application ID	app.timesafari in capacitor.config.ts, android/app/build.gradle, Firebase Android app
google-services.json	In android/app/; not committed if gitignored — local copy per developer
Gradle	Google services plugin applied (verify repo’s current build.gradle)
Permissions	POST_NOTIFICATIONS (API 33+); manifest entries for FCM
FCM token	Debug panel Register Token Now + ngrok POST /notifications/register
No APNs	N/A on Android

§8 — iOS-specific testing notes

Replace with Android-specific sections (draft topics below). Do not port:

• APNs silent delivery / Simulator unreliability (iOS framing)
• Force-quit via app switcher (iOS-specific policy)
• Low Power Mode (iOS) — Android has different battery saver APIs
• Focus / Do Not Disturb (iOS naming)

Port with Android wording:

• Two Simulate WAKEUP_PING buttons table — unchanged behavior

§11 — Troubleshooting (partial)

Reuse as-is:

• Refresh endpoint unreachable (ngrok, URL, 404, CORS note)
• Stale ngrok URL
• Plugin / JWT errors after refresh

Rewrite:

iOS troubleshooting	Android replacement
Push permission + VITE_FIREBASE_* + Xcode log	Permission (runtime POST_NOTIFICATIONS), logcat, Firebase Android config
Silent push not waking — backgrounded not force-quit, APNs key, wait 30–120s	FCM high-priority data, force-stop (STOP from settings), Doze, battery optimization, OEM autostart, token mismatch
Physical device + provisioning profile	USB debugging, correct build variant, Play vs debug signing if relevant

§13 — Related docs

Keep iOS-centric links as “see also”; add:

• android-physical-device-guide.md
• BUILDING.md — Android build commands (build:android:*)
• daily-notification-plugin Android docs (exact alarm, pending inspector on Android)

---

Android-Specific Topics Required

These sections do not exist in the iOS guide (or exist only by analogy) and must be written for the Android notification testing doc.

Firebase project setup

• Use the same Firebase project as iOS when testing the same backend, or document a dedicated timesafari-dev project.
• Add an Android app with package name app.timesafari.
• Enable Cloud Messaging (default on new projects).
• Download google-services.json and install under android/app/.
• Note: android/.gitignore may exclude google-services.json — developers copy locally; never commit secrets.

google-services.json

• Placement: android/app/google-services.json
• Sync after add: npx cap sync android, rebuild in Android Studio
• Verify build merges Firebase config (no “missing google-services” Gradle errors)
• Relationship to VITE_FIREBASE_* for the web layer / Capacitor JS Firebase initialization

Android notification permissions

• Android 13+ (API 33): POST_NOTIFICATIONS runtime permission — required for notification display; document interaction with data-only FCM wake (may still deliver to app code when permission denied — verify against current app behavior and document accurately).
• Android 12 and below: install-time grant model; fewer runtime prompts.
• App Settings → Notifications — manual enable path for testers.
• Link notification-permissions-and-rollovers.md for product-level permission UX.

FCM token handling

• Token obtained via Capacitor Push Notifications + firebaseMessagingClient.ts (same JS path as iOS).
• Register Token Now in debug panel → POST /notifications/register with platform: "android".
• Token rotation: when to re-register; duplicate skip behavior in panel.
• Ensure notification-wakeup-service stores/sends to the token shown in the panel for /debug/send-wakeup.
• Optional: adb cannot easily read FCM token — panel is source of truth (same as iOS).

Android background delivery behavior

• FCM data messages handled in foreground/background per Capacitor plugin and NativeNotificationService.ts.
• No APNs intermediary — document expected latency vs iOS.
• High-priority FCM for wakeup testing (align with backend message options).
• App in background vs foreground vs killed — different from iOS “swipe away” story:
  • Force stop (Settings → Force stop): delivery often blocked until user launches app again (stricter than iOS “backgrounded”).
  • Recent apps swipe: behavior varies by OEM/Android version — document “test with Home button background, not force stop.”
• pushNotificationReceived / listener registration at startup (main.capacitor.ts).

Doze Mode

• Device idle → deferred network and job execution.
• Testing: use adb shell dumpsys deviceidle (document safe dev-only commands) or unplugged idle wait.
• Explain why /debug/send-wakeup may succeed on server but device wakes late.
• Whitelisting app for tests (developer settings) — use cautiously; note production users won’t do this.

Battery optimization

• Settings → Apps → TimeSafari → Battery → Unrestricted vs Optimized.
• Manufacturer “battery saver” modes that restrict background network.
• Recommend Unrestricted (or equivalent) for local wakeup validation; warn that production users may remain optimized.

OEM restrictions (Samsung, Xiaomi, Oppo, etc.)

• Autostart / Background activity / Battery menus on Samsung, Xiaomi (MIUI), Oppo/ColorOS, Huawei, OnePlus, etc.
• Symptom: FCM works on Pixel but not on OEM device until autostart enabled.
• Provide a short “if wake fails on OEM, check…” checklist without exhaustive per-OEM screenshots (link community docs if needed).
• Physical device testing should include at least one stock-ish device (Pixel) and one OEM device when possible.

---

Proposed outline for doc/local-android-testing-ngrok.md

Suggested section order mirroring iOS doc for easy maintenance:

1. Title, audience, goal (Android physical device + ngrok + wakeup service)
2. Architecture overview (FCM direct to Android)
3. Prerequisites (Android Studio, device, Firebase Android app, non-prod build)
4. ngrok install, account, tunnel (reuse iOS §1)
5. Start notification-wakeup-service (reuse iOS §2)
6. ngrok HTTPS URL (reuse iOS §3)
7. Build and open Android project (new, replaces iOS §4)
8. Firebase setup for Android (new, replaces iOS §5 — no APNs)
9. Notification Debug Panel (reuse iOS §6)
10. Android configuration checklist (new, replaces iOS §7)
11. Android-specific testing notes (new, replaces iOS §8)
12. Recommended debug workflow (reuse iOS §9 + logcat)
13. Sample curl commands (reuse iOS §10 + platform: "android")
14. Troubleshooting (merge reusable + Android push rows)
15. Key source files (reuse iOS §12)
16. Related docs (iOS doc + Android device guide + BUILDING)

---

Wording and terminology substitutions

When adapting reused sections:

iOS doc term	Android doc term
iPhone	Android phone / device
Xcode console	logcat / Android Studio Logcat
build:ios:dev / test	build:android:dev / test
GoogleService-Info.plist	google-services.json
APNs / silent push	FCM data message / high-priority data
Bundle ID	Application ID / package name (app.timesafari)
Physical iPhone required for APNs	Physical device strongly recommended for Doze/OEM/FCM realism
platform: "ios" in curl	platform: "android"

---

Gaps to resolve while writing the Android guide

Research during authoring (code + notification-wakeup-service + daily-notification-plugin):

1. Exact FCM Android message priority and payload fields for WAKEUP_PING (parity with iOS data message).
2. Whether POST_NOTIFICATIONS denial blocks data message delivery to JS listeners on API 33+.
3. Gradle/Firebase plugin versions already in android/ — document exact files to touch.
4. Android Pending Notification Inspector parity with iOS panel section.
5. Whether emulator with Google Play image is acceptable for minimal FCM smoke tests vs mandatory physical device for wakeup SLA testing.

---

Document maintenance

Document	Role
local-ios-testing-ngrok.md	Canonical iOS + ngrok workflow (unchanged by this analysis)
This file	Reuse vs rewrite matrix and Android topic backlog
Future local-android-testing-ngrok.md	Operator guide for Android testers

When backend or debug panel behavior changes, update both platform guides’ shared sections in lockstep (or extract shared “ngrok + debug panel” snippet later — out of scope unless requested).