trent_larson/crowd-funder-for-time-pwa
4
1
Fork 2
Code Issues Pull Requests 24 Releases 5 Wiki Activity

WIP: new-activity notification #231

Draft
trentlarson wants to merge 80 commits from notify-api into master
pull from: notify-api
merge into: trent_larson:master
Conversation 0 Commits 80 Files Changed 88 +113 -9
1 changed files with 113 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 964cdb4509 - Show all commits

122
doc/local-ios-testing-ngrok.md
View File

@@ -163,7 +163,109 @@ curl -sS "$NGROK_URL/health"
---
## 4. Build and run the iOS app (physical device)
## 4. Firebase + APNs setup (first-time setup)
Complete this section once before your first physical-device push test. If Firebase and APNs are already configured for this app, skip to [section 5](#5-build-and-run-the-ios-app-physical-device).
### Create or access a Firebase account
1. Sign in with a Google account at [https://console.firebase.google.com/](https://console.firebase.google.com/).
2. If this is your first time using Firebase:
- Accept the Firebase terms.
- Create a new Firebase account/workspace when prompted.
3. No paid Firebase plan is required for local iOS notification testing. The free **Spark** plan is sufficient for:
- Firebase Cloud Messaging (FCM)
- APNs silent push testing
- local ngrok-based development
### Create a Firebase project
1. In the [Firebase Console](https://console.firebase.google.com/), click **Add project** (or **Create a project**).
2. Enter a project name (for example, `timesafari-dev`) and continue through the wizard.
3. **Google Analytics** is optional for this workflow; you can disable it for a simpler dev project.
4. When the project is created, open it. **Cloud Messaging** is available on all projects — you do not need a separate enable step for FCM.
### Register the iOS app in Firebase
1. In the project overview, click the **iOS** icon (**Add app** → iOS).
2. Enter the **Apple bundle ID**. It must **exactly** match the Capacitor / Xcode app ID:
- **`app.timesafari`** (see `appId` in `capacitor.config.ts` and the Xcode target **Bundle Identifier**).
3. App nickname and App Store ID are optional for local testing; continue.
4. Download **`GoogleService-Info.plist`** when prompted and keep it handy for the next step.
### Add GoogleService-Info.plist to Xcode
1. Open the iOS workspace generated by Capacitor (for example `ios/App/App.xcworkspace` after `npm run build:ios:dev`).
2. In the Project Navigator, select the main **App** group (or the folder that contains the iOS app target sources).
3. Drag **`GoogleService-Info.plist`** from Finder into that group.
4. In the dialog:
- Check **Copy items if needed** (so the file is copied into the project tree).
- Under **Add to targets**, ensure the main app target (not only the share extension) is checked.
5. Confirm the file appears under the app target in Xcode and is listed in **Build Phases** → **Copy Bundle Resources** if your project uses that phase for plists.
### Create an APNs Authentication Key
Apple uses APNs to deliver pushes to devices; Firebase needs an APNs key to talk to Apple on your behalf.
1. Sign in to [Apple Developer](https://developer.apple.com/account/) → **Certificates, Identifiers & Profiles**.
2. Open **Keys** → **+** (create a new key).
3. Name the key (for example, `Timesafari APNs Dev`).
4. Enable **Apple Push Notifications service (APNs)** and continue.
5. Register the key, then **Download** the `.p8` file. **You can download it only once** — store it securely.
6. Note:
- **Key ID** (shown on the key detail page)
- **Team ID** (top right of the developer portal, or **Membership** details)
### Upload APNs key to Firebase
1. Firebase Console → your project → **Project settings** (gear icon).
2. Open the **Cloud Messaging** tab.
3. Under **Apple app configuration**, select your iOS app (`app.timesafari`) if prompted.
4. Under **APNs Authentication Key**, click **Upload**.
5. Select the `.p8` file and enter:
- **Key ID**
- **Team ID**
6. Save. Firebase can now send FCM messages through APNs to your iOS app.
### Enable iOS capabilities in Xcode
1. Select the **App** target → **Signing & Capabilities**.
2. Click **+ Capability** and add **Push Notifications**.
3. Click **+ Capability** again and add **Background Modes**.
4. Under Background Modes, enable **Remote notifications**.
These match what silent / data wake flows expect for background delivery.
### Configure Firebase Admin for the backend
**notification-wakeup-service** uses the Firebase Admin SDK to send FCM (and thus APNs) messages from your Mac.
1. Firebase Console → **Project settings** → **Service accounts**.
2. Click **Generate new private key** and confirm download of the JSON file.
3. Store the JSON outside the repo (do not commit it).
4. Point the backend at it, for example:
```bash
export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/service-account.json"
```
The backend uses this credential to authenticate with Firebase when calling endpoints such as `/debug/send-wakeup`. Set the same variable (or the equivalent env var documented in **notification-wakeup-service**) in the shell where you run `npm run dev`, or add it to that repo’s `.env` per its README.
### Verify Firebase configuration
Before ngrok end-to-end testing, confirm:
- [ ] App builds and launches on a **physical** iPhone without Firebase/plist errors in Xcode.
- [ ] iOS shows the push **permission** prompt (or Settings → app → Notifications is enabled).
- [ ] **Notification Debug Panel** shows an FCM token (after permission).
- [ ] **Register Token Now** succeeds and ngrok (or local backend) shows `POST /notifications/register`.
- [ ] Backend health and Firebase Admin env are set so `/debug/send-wakeup` can run when you reach that step in the workflow below.
---
## 5. Build and run the iOS app (physical device)
From **crowd-funder-for-time-pwa**:
@@ -178,7 +280,7 @@ Ensure `VITE_FIREBASE_*` variables are set for the Capacitor build you use (see
---
## 5. Configure the Notification Debug Panel backend override
## 6. Configure the Notification Debug Panel backend override
The app normally calls `APP_SERVER` (from `VITE_APP_SERVER`). For local wakeup testing, override the notification API base URL without rebuilding.
@@ -219,7 +321,9 @@ getNotificationApiBaseUrl(); // → ngrok URL
---
## 6. Firebase and Xcode checklist (iOS)
## 7. Firebase and Xcode checklist (iOS)
This section is a quick verification checklist for the detailed Firebase/APNs setup steps above.
| Item | Action |
|------|--------|
@@ -234,7 +338,7 @@ Silent/data pushes used for wake typically use a **content-available** style pay
---
## 7. iOS-specific testing notes
## 8. iOS-specific testing notes
### Physical device required
@@ -267,7 +371,7 @@ Use the backend button to verify ngrok + refresh; use the simulator to verify ha
---
## 8. Recommended debug workflow
## 9. Recommended debug workflow
1. Start **notification-wakeup-service** on the Mac.
2. Start **ngrok** and copy the HTTPS URL.
@@ -281,7 +385,7 @@ Use the backend button to verify ngrok + refresh; use the simulator to verify ha
---
## 9. Sample curl commands
## 10. Sample curl commands
Set your tunnel base URL:
@@ -350,7 +454,7 @@ Confirm parameters (token vs deviceId, auth headers) in that repo’s README or
---
## 10. Troubleshooting
## 11. Troubleshooting
### Refresh endpoint unreachable
@@ -395,7 +499,7 @@ Confirm parameters (token vs deviceId, auth headers) in that repo’s README or
---
## 11. Key source files (crowd-funder-for-time-pwa)
## 12. Key source files (crowd-funder-for-time-pwa)
| File | Purpose |
|------|---------|
@@ -410,7 +514,7 @@ Confirm parameters (token vs deviceId, auth headers) in that repo’s README or
---
## 12. Related docs
## 13. Related docs
- [Notification Debug Panel (README)](../README.md#notification-debug-panel-dev-builds)
- [notification-system-overview.md](./notification-system-overview.md)