more package declarations
This commit is contained in:
462
docs/PUSH_NOTIFICATIONS_SETUP.md
Normal file
462
docs/PUSH_NOTIFICATIONS_SETUP.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# Push Notifications Setup Guide (FCM & APNs)
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers setting up Firebase Cloud Messaging (FCM) for Android and Apple Push Notification service (APNs) for iOS push notifications in the ShieldAI mobile app.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ Mobile │────▶│ API Gateway │────▶│ Notification │
|
||||
│ App │ │ /devices/* │ │ Service │
|
||||
└─────────────┘ └──────────────────┘ └────────┬────────┘
|
||||
│
|
||||
┌──────────────────────────────┼──────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
||||
│ Firebase │ │ Apple Push │ │ Redis (Rate │
|
||||
│ Cloud │ │ Notification │ │ Limiting) │
|
||||
│ Messaging │ │ Service │ │ │
|
||||
│ (Android) │ │ (iOS) │ │ │
|
||||
└────────────────┘ └─────────────────┘ └──────────────────┘
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Add the following to your `.env` file:
|
||||
|
||||
```bash
|
||||
# Firebase Cloud Messaging (FCM)
|
||||
FCM_PROJECT_ID=your-firebase-project-id
|
||||
FCM_CLIENT_EMAIL=service-account@your-project.iam.gserviceaccount.com
|
||||
FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
|
||||
|
||||
# Apple Push Notification (APNs)
|
||||
APNS_KEY_ID=your-key-id
|
||||
APNS_TEAM_ID=your-team-id
|
||||
APNS_BUNDLE_ID=com.yourcompany.shieldai
|
||||
APNS_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
|
||||
|
||||
# Redis (for rate limiting)
|
||||
REDIS_URL=redis://localhost:6379
|
||||
|
||||
# Rate Limits
|
||||
PUSH_RATE_LIMIT=100
|
||||
RATE_LIMIT_WINDOW_SECONDS=60
|
||||
```
|
||||
|
||||
## Firebase Cloud Messaging (FCM) Setup
|
||||
|
||||
### 1. Create Firebase Project
|
||||
|
||||
1. Go to [Firebase Console](https://console.firebase.google.com/)
|
||||
2. Click **Add project**
|
||||
3. Enter project name: `shieldai-production` (or your preferred name)
|
||||
4. Disable Google Analytics (optional)
|
||||
5. Click **Create project**
|
||||
|
||||
### 2. Enable Cloud Messaging
|
||||
|
||||
1. In Firebase Console, go to **Project settings**
|
||||
2. Scroll down to **Your apps** section
|
||||
3. Click the **Web** icon `</>` to add a web app
|
||||
4. Register app nickname: `ShieldAI API`
|
||||
5. **Do not** check "Also set up for Firebase Hosting"
|
||||
6. Click **Register app**
|
||||
7. Copy the `firebaseConfig` for later use in mobile app
|
||||
|
||||
### 3. Generate Service Account Key
|
||||
|
||||
1. Go to **Project settings** → **Service accounts**
|
||||
2. Click **Generate new private key**
|
||||
3. Save the downloaded JSON file securely
|
||||
4. Extract the following values:
|
||||
- `project_id`
|
||||
- `client_email`
|
||||
- `private_key`
|
||||
|
||||
### 4. Configure FCM in ShieldAI
|
||||
|
||||
Create a file `packages/shared-notifications/.fcm-config.json` (gitignored):
|
||||
|
||||
```json
|
||||
{
|
||||
"projectId": "your-firebase-project-id",
|
||||
"clientEmail": "service-account@your-project.iam.gserviceaccount.com",
|
||||
"privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
|
||||
}
|
||||
```
|
||||
|
||||
Set environment variables:
|
||||
|
||||
```bash
|
||||
export FCM_PROJECT_ID="your-firebase-project-id"
|
||||
export FCM_CLIENT_EMAIL="service-account@your-project.iam.gserviceaccount.com"
|
||||
export FCM_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
|
||||
```
|
||||
|
||||
### 5. Install Firebase Admin SDK
|
||||
|
||||
```bash
|
||||
cd packages/shared-notifications
|
||||
npm install firebase-admin
|
||||
```
|
||||
|
||||
## Apple Push Notification (APNs) Setup
|
||||
|
||||
### 1. Create App ID
|
||||
|
||||
1. Go to [Apple Developer Portal](https://developer.apple.com/account/resources/identifiers/list)
|
||||
2. Click **+** to create new identifier
|
||||
3. Select **App IDs** → **App**
|
||||
4. Enter description: `ShieldAI Mobile`
|
||||
5. Enter Bundle ID: `com.yourcompany.shieldai`
|
||||
6. Enable **Push Notifications** capability
|
||||
7. Click **Continue** → **Register**
|
||||
|
||||
### 2. Create APNs Key
|
||||
|
||||
1. Go to **Certificates, IDs & Profiles** → **Keys**
|
||||
2. Click **+** to create new key
|
||||
3. Enter key name: `ShieldAI APNs Key`
|
||||
4. Enable **Apple Push Notification service (APNs)**
|
||||
5. Click **Continue** → **Register**
|
||||
6. **Download the key** (`.p8` file) - you can only download once!
|
||||
7. Note the **Key ID** displayed
|
||||
|
||||
### 3. Configure APNs in ShieldAI
|
||||
|
||||
Convert the `.p8` file to PEM format:
|
||||
|
||||
```bash
|
||||
# Convert .p8 to PEM
|
||||
openssl pkcs8 -topk8 -nocrypt -in AuthKey_XXXXXX.p8 -out apns_key.pem
|
||||
|
||||
# Copy the PEM content
|
||||
cat apns_key.pem
|
||||
```
|
||||
|
||||
Set environment variables:
|
||||
|
||||
```bash
|
||||
export APNS_KEY_ID="XXXXXX"
|
||||
export APNS_TEAM_ID="YYYYYY"
|
||||
export APNS_BUNDLE_ID="com.yourcompany.shieldai"
|
||||
export APNS_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
|
||||
```
|
||||
|
||||
### 4. Configure in Xcode
|
||||
|
||||
In your iOS app's `Info.plist`:
|
||||
|
||||
```xml
|
||||
<key>UIBackgroundModes</key>
|
||||
<array>
|
||||
<string>fetch</string>
|
||||
<string>remote-notification</string>
|
||||
</array>
|
||||
```
|
||||
|
||||
Enable capabilities in Xcode:
|
||||
- **Push Notifications**
|
||||
- **Background Modes** → **Remote notifications**
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Device Registration
|
||||
|
||||
#### Register Device
|
||||
```http
|
||||
POST /api/v1/devices/register
|
||||
Authorization: Bearer <JWT_TOKEN>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"platform": "android",
|
||||
"fcmToken": "eXwR9...",
|
||||
"appVersion": "1.0.0",
|
||||
"osVersion": "Android 13"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"device": {
|
||||
"deviceId": "dev_1234567890_abc123",
|
||||
"platform": "android",
|
||||
"registeredAt": "2026-05-14T13:00:00.000Z"
|
||||
},
|
||||
"message": "Device registered successfully"
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Device Tokens
|
||||
```http
|
||||
PUT /api/v1/devices/:deviceId/tokens
|
||||
Authorization: Bearer <JWT_TOKEN>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"fcmToken": "new-token-here",
|
||||
"apnsToken": "new-token-here"
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Registered Devices
|
||||
```http
|
||||
GET /api/v1/devices
|
||||
Authorization: Bearer <JWT_TOKEN>
|
||||
```
|
||||
|
||||
#### Deregister Device
|
||||
```http
|
||||
DELETE /api/v1/devices/:deviceId
|
||||
Authorization: Bearer <JWT_TOKEN>
|
||||
```
|
||||
|
||||
## Mobile App Integration
|
||||
|
||||
### Android (React Native)
|
||||
|
||||
```javascript
|
||||
import messaging from '@react-native-firebase/messaging';
|
||||
import { API } from '@shieldai/api-client';
|
||||
|
||||
// Request permission
|
||||
async function requestPushPermission() {
|
||||
const authStatus = await messaging().requestPermission();
|
||||
const enabled =
|
||||
authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
|
||||
authStatus === messaging.AuthorizationStatus.PROVISIONAL;
|
||||
|
||||
if (enabled) {
|
||||
console.log('Push permission granted:', authStatus);
|
||||
}
|
||||
}
|
||||
|
||||
// Get FCM token
|
||||
async function getFCMToken() {
|
||||
const token = await messaging().getToken();
|
||||
return token;
|
||||
}
|
||||
|
||||
// Register device with API
|
||||
async function registerDevice() {
|
||||
try {
|
||||
const fcmToken = await getFCMToken();
|
||||
|
||||
const response = await API.post('/devices/register', {
|
||||
platform: 'android',
|
||||
fcmToken,
|
||||
appVersion: '1.0.0',
|
||||
osVersion: Platform.OS + ' ' + Platform.Version,
|
||||
});
|
||||
|
||||
console.log('Device registered:', response.data);
|
||||
} catch (error) {
|
||||
console.error('Failed to register device:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// Listen for token refresh
|
||||
messaging().onTokenRefresh(async (newToken) => {
|
||||
await API.put('/devices/tokens', {
|
||||
fcmToken: newToken,
|
||||
});
|
||||
});
|
||||
|
||||
// Handle foreground messages
|
||||
messaging().onMessage(async (remoteMessage) => {
|
||||
console.log('Foreground message received:', remoteMessage);
|
||||
// Show local notification
|
||||
});
|
||||
|
||||
// Handle background messages
|
||||
messaging().setBackgroundMessageHandler(async remoteMessage => {
|
||||
console.log('Background message received:', remoteMessage);
|
||||
});
|
||||
```
|
||||
|
||||
### iOS (React Native)
|
||||
|
||||
```javascript
|
||||
import messaging from '@react-native-firebase/messaging';
|
||||
import { API } from '@shieldai/api-client';
|
||||
|
||||
// Request permission
|
||||
async function requestPushPermission() {
|
||||
const authStatus = await messaging().requestPermission();
|
||||
const enabled =
|
||||
authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
|
||||
authStatus === messaging.AuthorizationStatus.PROVISIONAL;
|
||||
|
||||
if (enabled) {
|
||||
console.log('Push permission granted:', authStatus);
|
||||
}
|
||||
}
|
||||
|
||||
// Get APNs token
|
||||
async function getAPNSToken() {
|
||||
const token = await messaging().getToken();
|
||||
return token;
|
||||
}
|
||||
|
||||
// Register device with API
|
||||
async function registerDevice() {
|
||||
try {
|
||||
const apnsToken = await getAPNSToken();
|
||||
|
||||
const response = await API.post('/devices/register', {
|
||||
platform: 'ios',
|
||||
apnsToken,
|
||||
appVersion: '1.0.0',
|
||||
osVersion: Platform.OS + ' ' + Platform.Version,
|
||||
});
|
||||
|
||||
console.log('Device registered:', response.data);
|
||||
} catch (error) {
|
||||
console.error('Failed to register device:', error);
|
||||
}
|
||||
}
|
||||
|
||||
// Handle foreground messages
|
||||
messaging().onMessage(async (remoteMessage => {
|
||||
console.log('Foreground message received:', remoteMessage);
|
||||
// Show local notification
|
||||
}));
|
||||
```
|
||||
|
||||
## Testing Push Notifications
|
||||
|
||||
### Test with Firebase Console
|
||||
|
||||
1. Go to [Firebase Console](https://console.firebase.google.com/) → **Cloud Messaging**
|
||||
2. Click **Send your first message**
|
||||
3. Enter notification title and body
|
||||
4. Choose test device or all users
|
||||
5. Click **Send test message**
|
||||
|
||||
### Test with API
|
||||
|
||||
```bash
|
||||
# Send test push notification
|
||||
curl -X POST https://your-api.com/api/v1/notifications/send \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"userId": "user-123",
|
||||
"channel": "push",
|
||||
"title": "Test Notification",
|
||||
"body": "This is a test push notification",
|
||||
"data": {
|
||||
"type": "test",
|
||||
"action": "open_app"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Test with cURL (Direct FCM)
|
||||
|
||||
```bash
|
||||
curl -X POST https://fcm.googleapis.com/v1/projects/your-project-id/messages:send \
|
||||
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": {
|
||||
"token": "FCM_TOKEN_HERE",
|
||||
"notification": {
|
||||
"title": "Test Title",
|
||||
"body": "Test Body"
|
||||
},
|
||||
"data": {
|
||||
"type": "test"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Production Checklist
|
||||
|
||||
### FCM Configuration
|
||||
- [ ] Firebase project created
|
||||
- [ ] Service account key generated and stored securely
|
||||
- [ ] FCM environment variables configured
|
||||
- [ ] Firebase Admin SDK initialized
|
||||
- [ ] Test notifications sent successfully
|
||||
|
||||
### APNs Configuration
|
||||
- [ ] App ID created with push capability
|
||||
- [ ] APNs key generated and downloaded
|
||||
- [ ] Key converted to PEM format
|
||||
- [ ] APNs environment variables configured
|
||||
- [ ] Xcode capabilities enabled
|
||||
- [ ] Test notifications sent from simulator
|
||||
|
||||
### API Configuration
|
||||
- [ ] Device registration endpoints working
|
||||
- [ ] Token update endpoints working
|
||||
- [ ] Rate limiting configured
|
||||
- [ ] Error handling implemented
|
||||
- [ ] Logging for push notifications
|
||||
|
||||
### Mobile App Configuration
|
||||
- [ ] Push permissions requested
|
||||
- [ ] Token retrieval implemented
|
||||
- [ ] Device registration on app start
|
||||
- [ ] Token refresh handling
|
||||
- [ ] Foreground message handling
|
||||
- [ ] Background message handling
|
||||
- [ ] Notification display implemented
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### FCM Token Not Received
|
||||
- Check Firebase configuration in mobile app
|
||||
- Verify Google Services (Android) / GoogleService-Info.plist (iOS)
|
||||
- Ensure push permissions granted
|
||||
|
||||
### APNs Token Not Received
|
||||
- Verify App ID configuration in Apple Developer
|
||||
- Check APNs key configuration
|
||||
- Ensure background modes enabled in Xcode
|
||||
- Test on actual device (not simulator)
|
||||
|
||||
### Notifications Not Delivering
|
||||
- Check device registration status
|
||||
- Verify tokens are valid
|
||||
- Check rate limiting status
|
||||
- Review server logs for errors
|
||||
|
||||
### Token Refresh Issues
|
||||
- Listen for `onTokenRefresh` events
|
||||
- Update tokens via API immediately
|
||||
- Handle network errors gracefully
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Never expose service account keys** in client-side code
|
||||
2. **Always validate** device ownership on server
|
||||
3. **Use HTTPS** for all API calls
|
||||
4. **Implement rate limiting** to prevent abuse
|
||||
5. **Store tokens securely** using secure storage libraries
|
||||
6. **Deregister devices** on user logout
|
||||
|
||||
## Monitoring
|
||||
|
||||
Monitor the following metrics:
|
||||
- Push notification delivery rate
|
||||
- Token refresh frequency
|
||||
- Device registration failures
|
||||
- Rate limit hits
|
||||
- Notification open rate
|
||||
|
||||
## Support
|
||||
|
||||
- Firebase Support: https://firebase.google.com/support
|
||||
- Apple Developer Support: https://developer.apple.com/contact/
|
||||
- FCM Documentation: https://firebase.google.com/docs/cloud-messaging
|
||||
- APNs Documentation: https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server
|
||||
Reference in New Issue
Block a user