> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchtoday.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Push Notifications

> Send and handle push notifications in your app

## 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.

<CardGroup cols={2}>
  <Card title="iOS (APNs)" icon="apple" href="/push-notifications/ios">
    Configure APNs tokens and credentials
  </Card>

  <Card title="Android (FCM)" icon="android" href="/push-notifications/android">
    Configure Firebase Cloud Messaging
  </Card>

  <Card title="API" icon="server" href="/push-notifications/api">
    Create tokens and send notifications via curl
  </Card>

  <Card title="Guidance" icon="sparkles" href="/push-notifications/guidance">
    Scheduling, queues, and best practices
  </Card>
</CardGroup>

## 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:
   * [iOS Setup](/push-notifications/ios)
   * [Android Setup](/push-notifications/android)
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](/push-notifications/api)

## 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](/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](/essentials/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](/push-notifications/guidance).

## Next Steps

* [iOS Setup](/push-notifications/ios)
* [Android Setup](/push-notifications/android)