docs(notifications): add from-scratch Firebase and APNs setup to ngrok guide
Document first-time FCM/APNs configuration (project, plist, .p8 key, Admin credentials, Xcode capabilities) before the iOS build step, and renumber later sections so the checklist references the new flow.
This commit is contained in:
Jose Olarte III
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user