Skip to main content

​
Overview

Push notifications let FERAL send proactive alerts to your phone — health warnings, calendar reminders, smart-home events — even when the app isn’t in the foreground. FERAL supports both Firebase Cloud Messaging (FCM) for Android and Apple Push Notification service (APNs) for iOS.

​
Firebase Cloud Messaging (Android)

1

Create a Firebase project

Go to the Firebase Console and create a new project (or use an existing one).
2

Generate a service account key

Go to Project Settings → Service Accounts → Generate new private key. This downloads a JSON file.
3

Configure FERAL

export FERAL_FCM_SERVICE_ACCOUNT_PATH="/path/to/firebase-service-account.json"
The service account JSON contains sensitive credentials. Store it outside your project directory and never commit it to version control.
4

Register device tokens

Your Android app registers its FCM device token with FERAL’s API:
curl -X POST http://localhost:9090/api/channels/push/register \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "android",
    "device_token": "fMx7Q3...",
    "device_name": "Pixel 8 Pro"
  }'
Response:
{
  "status": "registered",
  "device_id": "dev_abc123"
}

​
Apple Push Notification service (iOS)

1

Create an APNs key

In Apple Developer → Keys → Create a Key. Enable Apple Push Notifications service (APNs).Download the .p8 key file. Note the Key ID shown on the page.
2

Find your Team ID

Your Team ID is in the top-right of the Apple Developer portal, or under Membership Details.
3

Configure FERAL

export FERAL_APNS_KEY_PATH="/path/to/AuthKey_XXXXXXXXXX.p8"
export FERAL_APNS_KEY_ID="XXXXXXXXXX"
export FERAL_APNS_TEAM_ID="YYYYYYYYYY"
export FERAL_APNS_BUNDLE_ID="com.feral.app"
export FERAL_APNS_ENVIRONMENT="production"  # or "sandbox"
Use "sandbox" for development builds and "production" for TestFlight / App Store builds.
4

Register device tokens

Your iOS app registers its APNs device token with FERAL:
curl -X POST http://localhost:9090/api/channels/push/register \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "device_token": "a1b2c3d4e5...",
    "device_name": "iPhone 15 Pro"
  }'

​
Notification Types

FERAL sends different notification categories depending on context:
CategoryPriorityExample
health_alertHigh”Your heart rate spiked to 142 bpm during rest”
calendarNormal”Team standup in 15 minutes”
smart_homeNormal”Front door unlocked at 11:42 PM”
proactiveLow”Based on your sleep score, consider an earlier bedtime”
approvalHigh”FERAL wants to send an email — approve?”

​
Device Management API

MethodEndpointDescription
POST/api/channels/push/registerRegister a device token
GET/api/channels/push/devicesList registered devices
DELETE/api/channels/push/devices/:idUnregister a device
POST/api/channels/push/testSend a test notification

​
Test a notification

curl -X POST http://localhost:9090/api/channels/push/test \
  -H "Content-Type: application/json" \
  -d '{ "device_id": "dev_abc123", "title": "Hello", "body": "Push is working!" }'

​
Troubleshooting

Verify the service account JSON path is correct and the file is readable. Check feral doctor for FCM connectivity status.
Ensure you’re using the correct environment (sandbox for dev, production for release). Confirm the bundle ID matches your app.
Device tokens expire when the app is reinstalled or the OS rotates them. Re-register the token from the mobile app.