Push Notification Configuration

A feature of CP Commerce Admin rather than an applet of its own: you write a notification, pick the website and the topic, and publish it now or schedule it, and the backend sends it through Firebase Cloud Messaging to every device subscribed to that topic. Nothing posts. Three things must line up — a Firebase credential on the website record, which BigLedger support places there; an app build registered with the same Firebase project; and devices subscribed to the topic. A publish that Firebase refused still shows the same success message, so prove a send on a test device, and a scheduled notification goes out only once its scheduled job has been added for your tenant.

Your job, and the screen for it

Overview

Push notifications are a feature of the CP Commerce Admin applet, not a separate applet. A marketing or operations user writes a notification under CP Commerce Admin → Notification, picks the website and the topic it goes to, and presses Publish Now (or schedules it). The backend sends it through Firebase Cloud Messaging (FCM) to every device subscribed to that topic, and the Customer Portal mobile app shows it and opens the linked page when the customer taps it.

Three things have to line up for a notification to arrive: the Website record must carry a Firebase service-account credential, the app build must be registered with the same Firebase project, and the customer’s device must be subscribed to the topic — which the Website’s Default Topic and Restrict Notification by Member settings decide. This page documents all three from the code. The old version of this page reproduced one customer’s Firebase project and build identifiers; those are deliberately absent here.

Where it fits

Upstream: Membership Admin and Customer supply the members and member labels that drive topic subscriptions. Downstream: nothing — a notification writes a read/unread link per subscriber and stops.

Screens and menus

All screens are in CP Commerce Admin (see that page for the full menu):

• Notification → listing, Create, Edit (Details tab with Publish Now; Scheduled tab; Posts sub-listing with Main / Manage Image).
• Topics → listing, Create, Edit (Details; Manage Image; Member Label Link — which member labels auto-subscribe to this topic).
• Website → edit → the Default Topic drop-down and the Restrict Notification by Member checkbox.

The storefront has a second door to the same records. The Webstore Management Dashboard’s Notification tile (the Website Builder side, under layout-menu/notifications-listing) opens a Notification Manager that writes the same notification record through the same endpoint as the console’s Notification screen, so a notification created on either side appears on both, and Publish Now and the Scheduled tab mean the same thing in both places. The differences are cosmetic: the tile’s listing is cards with a search box, an active/inactive toggle and a Scheduled Notifications calendar instead of a table; its create form does not ask for a website (it is already inside one) and starts with Status ACTIVE; and scheduling is on its edit screen, not its create form. The topic and post pickers on both forms are look-ups only — they do not create a topic or a post. So everyone who can open the Website Builder can also send a push notification from it; who those people are is the User Manager’s business.

Screenshots withdrawn; a recapture on a demo Firebase project is on the list.

Configuration

Before you can use it

1. A Firebase project with Cloud Messaging API (V1) enabled, one Android app and one iOS app registered under the package name / bundle ID your app build uses, and — for iOS — an APNs authentication key uploaded under Cloud Messaging → Apple app configuration. Download google-services.json and GoogleService-Info.plist from that project.
2. A service account for that project (Firebase console → Project settings → Service accounts → Generate new private key). The downloaded JSON is what the backend needs — see the next section.
3. A Website record in CP Commerce Admin for the storefront, with a code; the mobile app sends this code as the websiteCode header on every call, and the backend uses it to find the credential.
4. At least one Topic. Topics are tenant-wide, not per website; the website you send with decides which app’s copy of the topic is used. If you want every app install to receive notifications without signing in, also set it as the website’s Default Topic (below).
5. CMS notification permissions for the user who publishes — see Feature visibility / permissions.

The Firebase credential on the Website record

BigLedger does not use a Firebase server key or a platform-wide credential for Customer Portal pushes. It uses the service-account JSON stored on the website itself, found by the website code, and requires all eleven service-account fields to be present and non-null:

type, project_id, private_key_id, private_key, client_email, client_id, auth_uri, token_uri, auth_provider_x509_cert_url, client_x509_cert_url, universe_domain

If any is missing or null the call fails with INCORRECT_CONFIGURATION_WEBSITE_CONFIG_FIREBASE. The value is the service-account file pasted verbatim under one key:

{
  "firebase": {
    "type": "service_account",
    "project_id": "<your-firebase-project-id>",
    "private_key_id": "…",
    "private_key": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----\n",
    "client_email": "firebase-adminsdk-…@<project>.iam.gserviceaccount.com",
    "client_id": "…",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_x509_cert_url": "…",
    "universe_domain": "googleapis.com"
  }
}

Two facts about how the credential is used matter operationally:

• The credential is loaded once per tenant + website and then kept. A rotated key takes effect only after BigLedger restarts the service, not immediately — ask for that when you rotate it.
• Each website can point at its own Firebase project. A notification for website A is sent with website A’s credential to topic names prefixed with website A’s code, so an app build registered with project B never receives it.

Website settings that control subscriptions

Set on CP Commerce Admin → Website → edit. They are saved with the website and read by both the admin applet and the mobile app. Anyone with access to the Website edit screen can change them.

Note the two different notions of “default topic”: the app subscribes to the website’s Default Topic (above), while restoring a signed-in member’s subscriptions adds the topic whose Description is literally DEFAULT and fails with NO DEFAULT TOPIC IS DEFINED FOR THIS TENANT. KINDLY MAKE SURE 'DEFAULT' TOPIC IS SET. when there is none. Give the same topic both roles.

Topic naming in FCM

The FCM topic a device is subscribed to, and a notification is sent to, is built from the website code, the topic’s internal ID and the topic code. Renaming a topic’s code therefore changes the FCM topic; devices subscribed under the old code stop receiving until they re-subscribe.

App build

The Customer Portal app (Ionic 7 / Angular 19 / Capacitor 5) uses @capacitor/push-notifications 5.1. The base repository ships with placeholder app IDs; each customer build sets its own and adds:

• capacitor.config.ts → plugins.PushNotifications.presentationOptions: ["badge", "sound", "alert"] (how a foreground notification is shown).
• android/app/google-services.json — the Android Gradle build applies the Google Services plugin only when this file exists; without it the build succeeds and pushes silently do not work.
• ios/App/App/GoogleService-Info.plist, plus the Push Notifications and Background Modes → Remote notifications capabilities in Xcode and a provisioning profile that includes push.
• environment.isApp = true. The base repository has isApp: false in every environment file; the effects that subscribe to the Default Topic and restore a member’s subscriptions on a new token run only when this flag is true, so a web build never subscribes anything.

There is no BigLedger applet setting for any of this; the shared Application Settings screen of CP Commerce Admin has no notification keys.

Feature visibility / permissions

Notifications need API_TNT_DM_CMS_NOTIFICATION_OWNER / _ADMIN or the targeted API_TNT_DM_CMS_NOTIFICATION_CREATE (create, publish, initialise processors), _UPDATE, _DELETE, _READ. Assign them through CP Commerce Admin → Settings → Permission Set / Role Permission. The app’s own subscription calls need no permission: they are made for the website, not for a user, so there is nothing to grant on the app side.

Fields

Notification — Create / Details

Title becomes the notification’s heading and Description its body, exactly as typed; Description is optional, so a title-only notification is allowed.

Notification — Scheduled tab

Code is an optional label for the schedule; the server uses it only to name the schedule in its own log when the notification behind it has been deleted.

Topic — Create

Lifecycle and effects

Push notifications are not documents: nothing posts, no stock or GL is touched. What happens on each action:

Publish Now needs a website (without one: Kindly Provide the appropriate websiteCode). It marks the notification published, loads the website credential, loads the topic (refused if it is gone), builds the message (title, body, first post image, deep link) and sends it to the topic. It then adds one read/unread entry per subscriber of the topic — this is what the app’s in-app notification list shows.

A Firebase refusal does not fail the publish. The error comes back as a message in the reply instead, so the read/unread entries are created even when Firebase rejected the send. The admin screen does not show that message: its toast is the fixed text The notification has been published successfully whatever Firebase said, and the notification is marked sent. So the screen cannot tell you a send worked — prove it on a test device subscribed to the topic, and if nothing arrives, ask BigLedger support for the reply in the server log.

Scheduled → a schedule on the notification. The scheduled job NOTIFICATION_SCHEDULER_PROCESSOR picks every schedule that is due and not deleted, publishes exactly as above using the schedule’s website, then either moves the next run on by the recurrence rule (recurring) or ends the schedule (one-off). A schedule whose notification has been deleted is skipped.

Check that the job is scheduled before you schedule anything. NOTIFICATION_SCHEDULER_PROCESSOR is not in the default set of scheduled jobs a new tenant is given, so it has to be added deliberately in the Scheduler Applet. Assume you do not have it until you have looked. Without it a scheduled notification saves correctly, shows a future Scheduled Datetime, and is never sent — no error, no status change, nothing on the screen that would tell you. If you need scheduled sends, get the job scheduled first and send one test notification dated a few minutes out to prove it.

Device side (app builds only): on start the app checks permission, prompts, registers for push and keeps the device token on the device — across logout too. Then, if Restrict Notification by Member is false and a Default Topic is set and not yet subscribed, it subscribes the device to that topic without anyone signing in. On sign-in (or when restricted) it restores the member’s subscriptions for this device: the member’s outdated device tokens are unsubscribed and removed, and the member’s label-linked topics plus the DEFAULT topic are subscribed under the new token. Unsubscribing a topic in the app removes that subscription.

Tap on a notification → if it carries a deep link the app navigates to it; otherwise it just opens.

Member Label Link on a topic → subscribes every member carrying that label (with a stored device token) to the topic; removing the link unsubscribes them.

Related applets

• CP Commerce Admin — the applet this feature belongs to; Website, Topics and Notification menus.
• Membership Admin — member classes and labels that the Topic → Member Label Link uses to build segments.
• Customer — the customer / member records that carry the labels.

Troubleshooting

Related documentation

• CP Commerce Admin — Notification, Topics, Website settings, permissions.
• E-Commerce module
• Capacitor Push Notifications plugin and Firebase Cloud Messaging — vendor documentation for the native side.