Skip to main content

​
Overview

Push notifications help you reach users when they are away from the app. They are most effective when they are timely, relevant, and respectful of user preferences. In Launch, notifications are sent directly through APNs on iOS and FCM on Android to give you full control over payloads, delivery, and routing.

​
Prerequisites

  • Apple Developer account (APNs)
  • Firebase project (FCM)
  • Development build for native entitlements
  • Backend env vars set for APNs/FCM (copy from apps/api/example.env)
APNs (Apple Push Notification service) is Apple’s gateway for delivering pushes to iOS devices. FCM (Firebase Cloud Messaging) is Google’s gateway for Android. We send directly to both services instead of using Expo Push so we can control authentication, payload structure, delivery timing, and future routing logic without relying on a relay.

iOS (APNs)

Configure APNs tokens and credentials

Android (FCM)

Configure Firebase Cloud Messaging

API

Create tokens and send notifications via curl

Guidance

Scheduling, queues, and best practices

​
How It Works

┌─────────────┐     ┌─────────────┐
│  Your API   │────►│  APNs/FCM   │
│             │     │             │
└─────────────┘     └─────────────┘
       │
       ▼
┌──────────────────┐
│ iOS/Android Apps │
└──────────────────┘
  1. The app requests permissions and registers a native device token.
  2. The token is stored per user in device_tokens on the backend.
  3. Your API sends a notification through APNs (iOS) or FCM (Android).
  4. The device receives and displays the notification.

​
API Flow (iOS + Android)

When a user opts in on the onboarding screen, the app registers a native device token and stores it in the backend. Your API then targets those tokens when sending a push. APNs uses your bundle ID as the topic, and FCM uses your Firebase project to route the message to the correct app. Key pieces in this repo:
  • apps/mobile/app/onboarding/push-notifications.tsx
  • apps/mobile/lib/notifications.ts
  • apps/api/src/lib/push/apns.ts
  • apps/api/src/lib/push/fcm.ts
  • apps/api/src/routes/api/push.ts
  • apps/api/src/routers/push.ts

​
Steps

  1. Configure credentials:
  2. Rebuild the app (push entitlements require a native build).
  3. Use the onboarding screen to register a device token.
  4. Send a test push from your API: API Setup

​
Test Checklist

  • iOS device receives a test push
  • Android device receives a test push
  • Token is stored on the backend for the signed-in user

​
Troubleshooting

Start with platform setup guides, then see Troubleshooting.

​
Remove / Disable

If you are not shipping push, skip the onboarding step and remove token registration in apps/mobile/lib/notifications.ts. For production removal guidance, see Removing Features.

​
Best Practices

  • Ask for permission only when there is clear value.
  • Keep payloads short and actionable.
  • Avoid excessive sends; let users control frequency.
  • Use targeting for relevance instead of broadcasting by default.
  • For scheduling and queueing strategies, see Guidance.

​
Next Steps