Push notifications
optional, with your own Firebase project.

01What you need

Push needs two things (docs/PUSH.md):

1. your server holds a Firebase service account, so it can send;
2. your app is built with your Firebase project's configuration, so the device can register.

Users then choose per notification group whether push is used (Notification settings).

021. Create a Firebase project

1. Open the Firebase console (console.firebase.google.com) and create a project. Cloud Messaging is on by default.
2. Add the apps you ship: Android (your application ID from app/android/app/build.gradle.kts), iOS and macOS (your bundle ID), and web if you use the web app.

032. Server: the service account

1. Create the key. Firebase console, Project settings, Service accounts, Generate new private key. A JSON file downloads.
2. Give it to the server. Easiest, and the way that works with Docker: open the operator console, Integrations, paste the whole JSON into Firebase service account (JSON), save, and press Test. It answers "Signed in to project …" when Google accepts it.
3. Or, without Docker: store the file on the server outside any web folder and outside Git, set FCM_SERVICE_ACCOUNT_FILE=/path/to/service-account.json in .env and restart the server.

The Status page then shows Push (Firebase) as working, and the app's push option appears for users.

043. App: your Firebase configuration

From the app/ folder:

dart pub global activate flutterfire_cli
flutterfire configure --out=lib/push/firebase_options.dart

This overwrites the stub lib/push/firebase_options.dart with your project's values. Nothing else in the code changes. At start the app checks that file; with real values it starts Firebase after sign-in, asks for the notification permission and registers the device token with your server (app/lib/push/push_service.dart).

Do not commit your generated firebase_options.dart, google-services.json or GoogleService-Info.plist to a public repository. app/.gitignore already excludes google-services.json and GoogleService-Info.plist.

Android

Nothing more. On Android 13 and newer the app asks for the notification permission.

iOS and macOS

1. Choose your Team in Xcode under Signing & Capabilities.
2. Add the Push Notifications capability (and on iOS, Background Modes, Remote notifications).
3. Upload your APNs authentication key in the Firebase console, Project settings, Cloud Messaging.

Web

1. Create a Web Push key pair in the Firebase console, Project settings, Cloud Messaging, Web Push certificates, and put the public key into kWebPushVapidKey in lib/push/firebase_options.dart. Without it push stays off on the web.
2. Add web/firebase-messaging-sw.js, a service worker that initialises Firebase with your web app's values (Firebase documentation: "Receive messages in a web app"). The page must be served over HTTPS.

05Check that it works

Sign in on a device and open Settings. "Push on this device" says one of these:

Then trigger a notification, for example a price alert that fires at once, and confirm the device receives it. Settings, Notification settings, Devices shows whether this device registered a push token and lets the user remove it.