A deep-dive into Web Push Notifications with Drupal using Push Framework Notifications

I’m one of the maintainers of the Push Framework Notifications module. Since we started to work on this module in, I have integrated it into three different Drupal instances. This article is a follow-up of an article I published here on August 8, 2023.

From a user’s perspective, the process unfolds as follows:

1. Grant the browser permission to send notifications to your device or browser.
2. Subscribe to specific events to receive push notifications (for example, when someone replies to your comment or mentions you).

An important requirement is that the site should be installed as a PWA (Progressive Web App) from your browser on your device to receive push notifications.

On desktop, this isn’t necessary, as some browsers support sending notifications natively.

Here’s a short demo video showing how it works on my iOS device when used as a PWA. I captured the screen from my iOS device using QuickTime. You can see how CCNS.news is installed as a PWA. After logging in, I can subscribe to new comments on a link. When subscribing, a permission notification message pops up, which I have to approve to receive notifications from the PWA. When approved, my subscription is saved. Now, with another user (admin), I post a comment and my iOS device will receive a push notification of this event after a couple of minutes (these triggers are executed by two cron jobs).

I didn’t manage to record the notifications in the screen recording with QuickTime on my device, this seems to be an Apple issue. However, when I opened the Notifications Center, the notifications were there. On this site you can subscribe to push notifications, and then someone posts a new comment on a link.

CCNS.news installed as a PWA on iOS:

When you click the ‘Subscribe to…’ link:

…you will see a confirmation notification indicating that you are subscribed to receive push notifications when a new comment is published on this content:

View my notifications settings and active subscriptions:

Before you install and start using the module, make sure to read the instructions in the README file: https://git.drupalcode.org/project/pf_notifications/-/blob/1.0.x/README.md?ref_type=heads

When you enable / install the Push framework notifications module from the Extend page:

As you can see, the module has many dependencies that will also be installed. The two direct dependencies for Push Framework Notifications are DANSE and Push Framework.

As mentioned earlier, I strongly recommend installing and configuring the PWA contrib module as well. This enables mobile (web) push notifications to be sent by a Drupal-powered Progressive Web App or web application.

As a website owner with administrator privileges, you can access the features listed in the admin interface.

/admin/config/system/push_framework/pf_notifications

• Generate a VAPID keypair
• Edit the push notification message contents (title, message, favicon and link). You can also programmatically edit these values with a hook hook_pf_notifications_push_data.
• Test if subscribing and sending a push notification works on your device, see this video.
• /admin/reports/danse
  View the logs of DANSE related notification events.
• /admin/reports/push-subscriptions
  View the all subscriptions for push notifications per user.

Frontend components in pf_notifications

Let’s highlight some key parts of the frontend.

• Javascript files.

  • pf_notifications.init.js
  • pf_notifications.notifications_settings.js
  • pf_notifications.service_worker.js
  • pf_notfications.subscribe.js

Some points about the service worker (pf_notifications.service_worker.js):

• Listen to incoming ‘push’ messages from vendors to trigger push notifications on the device.
• Listens to notification modal clicks on the device.
• Shows notifications to the user.

Backend components in pf_notifications and required modules

Let’s highlight some key parts of the backend:

• Drupal

  • Contrib module Push Framework Notifications (drupal/pf_notifications)
  • Contrib module DANSE (drupal/danse)
  • Contrib module Push Framework (drupal/push_framework)
  • Optional: PWA (drupal/pwa)

• Cronjobs

  • danse_cron: collect unprocessed danse_event items and create queue items for the push framework queue.
  • push_framework_cron: collect created DANSE events in the push framework queue and process them.

• Web Push library for PHP
  This library is included as a dependency of the pf_notifications module. It acts as the middleware layer, sending data between the push notifications service (see third-party components section) and the Drupal site. That said, Drupal acts as the backend for handling push notifications. The library contains a Subscription class, with which you can create Subscription objects that require the following data:

  • endpoint (see next section)
  • keys and tokens

Third-party / vendor endpoints

These are the device and software vendors associated with the device or browser you’re using for the PWA.

• Google

  • Chrome on desktop
  • Chrome on Android

• Apple

  • Safari on desktop
  • Safari on iOS

• Mozilla

  • Firefox on desktop

• Microsoft

  • Edge on desktop

They run background services which pushes notification messages to your device or browser. You can identify each vendor by the following endpoints:

• Android: android.googleapis.com
• Chrome/Google: fcm.googleapis.com
• Firefox: updates.push.services.mozilla.com
• Mozilla: updates-autopush.stage.mozaws.net
• Mozilla: updates-autopush.dev.mozaws.net
• Edge/Microsoft: notify.windows.com
• Safari/Apple: push.apple.com

DANSE + Push Framework configuration with Push Framework Notifications

See https://sebastix.nl/blog/exploring-subscriptions-and-notifications-with-drupal-danse-module/ for detailed info how to configure subscriptions with DANSE in Drupal.

1. Enable submodule(s) DANSE Content for handling content type events
2. Set the permission Access POST on Push notification subscription resource to certain user roles at /admin/people/permissions:
3. Config DANSE for one or more content types. Example of /admin/structure/types/manage/link: Enable to enable subscriptions for new comments placed on an individual node of content type ‘Link’ for the selected user roles.
4. Check if the DANSE subscription widget is enabled as a field in the display of the content type. Example of /admin/structure/types/manage/link/display:
5. In this example I enabled the DANSE settings for comments on the content type Link. It’s important to also enable the DANSE settings for the comment type linked to this content type (/admin/structure/comment/manage/link_comment). In my case I needed to enable the publish checkbox. Enable subscription setting for published comments.
6. Generate a VAPID keypair at /admin/config/system/push_framework/pf_notifications:

There are two cronjobs responsible for handling all subscription-related events and for sending notifications:

1. danse_cron
   This will create the DANSE notification events (entities) and queue items in the Push Framework queue.
2. push_framework_cron
   This will collect the created DANSE notification events (from the Push Framework queue), and in the next iteration of this cronjob, those queued items will be processed.

You can check the created queue items and their states at admin/config/system/queues/jobs/push_framework.

View your notifications settings (in development)

When you go to your user page, there is a menu tab item ‘Notification settings’ which will open the URL /user/{user}/danse/pf_notifications.

Notifications settings in a browser:

On a iOS mobile device with the PWA:

When you click the test / show notification button for the first time:

When you approve to receive notifications, you will see the test notification message:

Here you can see that the user has three subscriptions (each subscription key is a subscription):

Debugging & resetting things

Since there are many configuration options to set, you may want to start over if you’re debugging or developing a project.

1. Open /admin/pf_notifications/reset-keys to delete the current VAPID keys, remove all subscriptions, and unregister the service worker in your browser.
2. Uninstall the pf_notifications module.

3. Unregister the service worker in your browser.

   1. For Safari on MacOS this can help, paste it in your developer console:

      navigator.serviceWorker.getRegistrations()
        .then(registrations => {
          registrations.map(r => {
            r.unregister()
          }) 
        })

4. Install the pf_notifications module again
5. Clear / reset the Drupal cache and start testing from scratch.

Create a push notification programmatically

To use direct notifications, bypassing DANSE and Push Framework, you can use the module’s service. Specifically, two methods are available:

• \Drupal::service('pf_notifications.subscription')->subscriptionResponse($op, $danse_key, $entity, $response, 1, FALSE) which can be found in src/Service/Subscription.php.

Examples can be found in the README.

Other caveats

• Make sure the contributed module PWA Service Worker is not enabled; otherwise two service workers will be active, causing a conflict.
• Users with subscriptions on multiple devices will receive notifications only on the device that was used to subscribe first. For example, if you subscribe on your mobile device first and then subscribe from a browser, you will receive notifications only on the mobile device. See also this issue. In this example, the user has subscriptions on two devices (clients), but push notifications will be delivered to only one device—the one used to subscribe first.
• If you check /admin/config/system/push_framework/pf_notifications after subscribing with a user and the subscription isn’t there (or after you unsubscribe), you may need to flush the Drupal caches and reload the page.
• A Push Framework notification can be delivered only once. If you’re using multiple channels (for example, email and push notifications), only the first configured channel will work. Check the settings at /admin/config/system/push_framework and make sure you set the order with Push framework notifications channel before other channels, for example like this: The contrib module Push Framework Email is also enabled here.
• Sending push notifications to PWA’s on iOS does not work? See https://github.com/web-push-libs/web-push-php/issues/411. I found the solution here: https://github.com/web-push-libs/web-push-php/issues/398#issuecomment-2762941713 and fixed it in this commit.
• When you click the “Subscribe to this…” link, you will see an “Unsubscribed from …” notification, and no subscription entry is saved in Drupal. This was due a bug in pf_notifications.subscribe.js on line 205, which is fixed in this commit.
• If you don’t see any results in the DANSE event report (/admin/reports/danse), check your DANSE settings. In the example above, I needed to enable DANSE settings for the content type AND for the comment type (enable the publish checkbox, see step 5 in “DANSE + Push Framework configuration with Push Framework Notifications”).
• Testing push notifications in Apple’s iOS Simulator does not work.

Other useful resources

• https://whatpwacando.today/notifications
• https://open-web-advocacy.org/walled-gardens-report/
• https://tomayac.github.io/pwa-feature-detector/

What’s next?

If you’ve read this far, you’ll likely agree that this topic can be quite complex. I believe there’s value in simplifying these ideas and tools. When a solution is easier to use, adoption tends to increase. Broader adoption then helps grow the open web through open, permissionless technology. The open web movement is a vital counterweight to the gatekeeping practices of BigTech.

Let’s keep pioneering, with open and permissionless web technology.