Skip to main content
Local notifications work out of the box. Remote push requires APNs (iOS) and FCM (Android) credentials.

iOS Setup (APNs)

EAS Build handles APNs certificates automatically. Just ensure:
  1. Push Notifications capability is enabled in Apple Developer Portal
  2. app.json includes:
Build with eas build --platform ios.

Android Setup (FCM)

  1. Create a Firebase project at console.firebase.google.com
  2. Add your Android app (use package name from app.json)
  3. Download google-services.json to apps/app/
  4. 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.
See Expo Push Notifications for detailed setup.

Usage

Request Permission

Toggle Push Notifications

Schedule Local Notification

Send Remote Notification (Backend)

Get the push token from your app:
Send from Node.js backend:
See Expo Push Service.

Handle Notification Taps

The notification store handles this automatically via initialize(). 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
No manual setup required - just use the store.

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
Channels are created automatically on first notification. No manual configuration needed.

Permission Denied Alerts

When users deny permission, a helpful alert offers to open Settings:
The alert includes:
  • 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 permissionStatus is 'granted'
  • For iOS remote: use physical device, verify APNs setup
  • For Android: verify google-services.json is in place
Push token is null?
  • Expected on web platform
  • On mobile: check permission was granted first
  • On emulator: mock token is returned (check logs)
Permission denied?
  • The store shows an alert prompting users to open Settings
  • Check permissionStatus for current state
Token changed unexpectedly?
  • 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