Notification Settings
Configure APNs and FCM notification channels so Storefront can deliver push notifications to your customers.
Notification Settings
Notification channels connect Storefront to Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM) so you can deliver push notifications to your customers' devices.
Navigate to Storefront → Settings → Notifications to manage channels.
Adding a Notification Channel
Navigate to Storefront → Settings → Notifications.
Click New Channel.
Enter a Name (e.g., "iOS APNs Production").
Select the Scheme: apn for iOS or fcm for Android.
Fill in the credentials for the selected scheme (see below).
Click Save.
APNs (Apple Push Notification service)
For iOS devices, using token-based (.p8) authentication.
| Field | Description |
|---|---|
Key ID (key_id) | The 10-character key ID from your Apple Developer account |
Team ID (team_id) | Your Apple Developer Team ID |
App Bundle ID (app_bundle_id) | Your app's bundle identifier (e.g., com.yourcompany.app) |
Private Key Content (private_key_content) | Paste the contents of the .p8 authentication key file (it's a textarea, not an upload) |
Environment (environment) | Auto (default), Production or Sandbox — see below |
Download the .p8 key from Apple Developer → Certificates, Identifiers & Profiles → Keys. Open the file in a text editor and copy its contents into the Private Key Content field.
Environment. Apple issues different device tokens to development builds (sandbox) and to TestFlight / App Store builds (production). With Auto, Storefront sends to production first and retries in sandbox when Apple rejects a token as belonging to the other environment, so one channel serves both kinds of build. Choose Production or Sandbox to only ever use one. Channels created before this setting existed keep their Production toggle, which now only decides which environment is tried first.
FCM (Firebase Cloud Messaging)
For Android devices, using the FCM v1 API (service-account based).
| Field | Description |
|---|---|
Firebase Credentials JSON (firebase_credentials_json) | Paste the full contents of your Firebase service account JSON file |
Android Channel ID (android_channel_id) | Optional. The Android notification channel to post to. Leave empty to use the app's default channel |
To download the service-account JSON:
- Go to Firebase Console → Project Settings → Service Accounts
- Click Generate new private key
- Open the downloaded JSON in a text editor and paste its entire contents into the Firebase Credentials JSON field
The channel uses these credentials directly; your Fleetbase instance does not need its own Firebase project. Self-hosted installs can set a default Android channel for all stores with the STOREFRONT_PUSH_ANDROID_CHANNEL_ID environment variable.
The legacy "Server Key" / "Sender ID" fields are deprecated by Google and are not used by this notification channel. If you have older docs referencing those, ignore them — Storefront uses the modern FCM v1 service-account flow.
Which channel is used
Store-level and network-level channels can both exist. For each device, Storefront uses the channels of:
- the store or network app the device registered from,
- then, for a marketplace order, the network,
- then the store.
If Apple or Google report that a token belongs to a different app or Firebase project, the next channel is tried. Configure channels on the network when your customers use a network (marketplace) app, and on the store when they use a single store's app.
Your app registers device tokens with POST /storefront/v1/customers/register-device — see Customer Notifications. Tokens that Apple or Google report as no longer valid are removed automatically, and every failed delivery is logged with the reason.
Testing a channel
Click Send test next to a channel, paste a device token from a phone running your app, and send. For APNs channels you can pick the environment to test, or leave it empty to try the channel's environments in order. The result shows Apple's or Google's answer for each attempt, for example:
| Result | Meaning |
|---|---|
sent | The provider accepted the notification |
wrong_environment (BadDeviceToken) | The iOS token belongs to the other APNs environment |
wrong_app (DeviceTokenNotForTopic, SenderId mismatch) | The token belongs to another app or Firebase project — check the bundle ID or service account |
dead (Unregistered) | The app was uninstalled or the token expired |
error | Credentials or provider problem — the message explains what failed |
Notification channels can be configured at the store level or the network level. Network-level channels are used for customers of the network's app across all member stores.