Progressive Web App - Notifications

Lets visitors subscribe their browser to web push notifications, and sends
them through the Firebase
Cloud Messaging HTTP v1 API.

Visitors opt in through a block — a toggle button or an explicit allow/deny
form. Administrators can send an ad hoc notification from the admin UI, and
other modules can send programmatically or through a Rules action.

Upgrading from 8.x-1.x? Read this first

Google decommissioned the legacy FCM HTTP API on 20 June 2024.
The server key that 8.x-1.x authenticated with is no longer accepted by any
endpoint, so that branch cannot send on any Drupal version.

2.x uses a Google service account instead, so the credentials
are different and are configured in a different place. Every subscriber
must subscribe again, because registration tokens are bound to a
Firebase sender. See
Upgrading
from 8.x-1.x in the README.

Requirements

• Drupal 10.3 or 11
• PHP 8.1 or newer
• A Firebase project with a registered web app

The PWA module is not
required. If it is installed, its app icon is reused for notifications.

Installation

1. composer require drupal/pwa_firebase_notification

2. Enable the module.
3. Collect three things from the
   Firebase console:
   • Service account key — Project settings → Service
     accounts → Generate new private key. Store the JSON file
     outside the web root; the module stores only the path to it, so
     the key never lands in exported configuration.
   • Web app configuration — Project settings → General →
     Your apps → your web app → SDK setup and configuration.
   • Web push certificate — Project settings → Cloud
     Messaging → Web configuration → Web Push certificates → Generate key
     pair.
4. Enter them at
   /admin/config/services/pwa-firebase-notification.
5. Grant Subscribe to PWA notifications to the roles that should be
   able to subscribe, usually including anonymous.
6. Place the PWA notification subscription block.

The Firebase
setup section of the README walks through this in more detail.

Notable behaviour

• Notification permission is requested only when the visitor activates the
  control, never on page load.
• The Firebase JavaScript SDK version is a setting, so a broken SDK release
  does not need a module release to escape.
• Expired subscriptions are treated as routine cleanup rather than errors:
  tokens FCM rejects permanently are removed automatically, and are counted
  separately from real delivery failures. A transient outage never deletes a
  subscription.
• Subscriptions record the token, the owning user, the language and two
  timestamps — no user agent and no IP address.
• The subscription endpoint is POST-only, permission-controlled and rate
  limited.

Rules

Enable the PWA Firebase Notification Rules submodule for a
Send web push notification action. It requires
Rules.

Credits

Originally based on code from
PWA issue
#2956352.