iOS Setup (APNs)
EAS Build handles APNs certificates automatically. Just ensure:- Push Notifications capability is enabled in Apple Developer Portal
app.jsonincludes:
eas build --platform ios.
Android Setup (FCM)
- Create a Firebase project at console.firebase.google.com
-
Add your Android app (use package name from
app.json) -
Download
google-services.jsontoapps/app/ - For server-side sending, set up FCM credentials in your backend: Supabase: Upload your Firebase service account JSON in the Supabase Dashboard under Integrations → Firebase. Convex: Add your Firebase service account JSON as an environment variable in the Convex Dashboard.
The legacy FCM Server Key is deprecated. Firebase now uses HTTP v1 API with OAuth 2.0 service account authentication. All server credentials should be configured in your backend dashboard, not in client-side environment variables.
Usage
Request Permission
Toggle Push Notifications
Schedule Local Notification
Send Remote Notification (Backend)
Get the push token from your app:Handle Notification Taps
The notification store handles this automatically viainitialize(). For custom handling:
Automatic Initialization
The notification store initializes automatically on app startup:- Requests permission status
- Registers for push tokens (on physical devices)
- Sets up notification listeners
- Handles token refresh when tokens are invalidated
- Configures Android notification channels
API Reference
Notification Store
Notification Service
Features
Physical Device Detection
Push tokens only work on physical devices. The service automatically detects emulators/simulators and returns mock tokens for development.Token Refresh Handling
Push tokens can be invalidated by the OS. The store automatically listens for token changes and re-registers when needed.Android Notification Channels
Android 8.0+ requires notification channels. Shipnative configures a default channel automatically with:- Maximum importance (ensures notifications appear prominently)
- Vibration pattern
- Sound enabled
- Badge support
- Show on lockscreen
Permission Denied Alerts
When users deny permission, a helpful alert offers to open Settings:- Clear explanation of what permission enables
- “Open Settings” button (deep links to app settings)
- “Maybe Later” option
- Platform-specific instructions (iOS vs Android)
Backend Synchronization
Push token is automatically synced to your backend:Notification Badge Management
Control app badge counts on iOS and Android:Analytics Integration
Notification events are automatically tracked with PostHog:Limitations
- Web: Push tokens return
null. Remote push via Expo not supported on web. - Emulators: Remote push doesn’t work. Mock tokens returned for development.
Troubleshooting
Notifications not appearing?- Check
permissionStatusis'granted' - For iOS remote: use physical device, verify APNs setup
- For Android: verify
google-services.jsonis in place
- Expected on web platform
- On mobile: check permission was granted first
- On emulator: mock token is returned (check logs)
- The store shows an alert prompting users to open Settings
- Check
permissionStatusfor current state
- Normal behavior - tokens can be invalidated by the OS
- The store handles this automatically via
addPushTokenListener
Next Steps
Mock Services
Test notifications without credentials
Analytics
Track notification opens and engagement

