Action Push Web is a Rails web push notification gem for PWAs using the Push API.

bundle add action_push_web
bin/rails action_push_web:install:migrations
bin/rails db:migrate
bin/rails g action_push_web:install

To load VAPID details from ENV or Rails credentials, use ERB in config/push.yml.

# config/push.yml
shared:
  web:
    vapid:
      subject: <%= ENV["VAPID_SUBJECT"] || Rails.application.credentials.dig(:vapid, :subject) %>
      public_key: <%= ENV["VAPID_PUBLIC_KEY"] || Rails.application.credentials.dig(:vapid, :public_key) %>
      private_key: <%= ENV["VAPID_PRIVATE_KEY"] || Rails.application.credentials.dig(:vapid, :private_key) %>

Web Push notifications require the following setup:

1. Register service worker triggered by user gesture (like clicking a button).
2. Request Notification permission from browser
3. Once granted, subscribe to the push service using service worker registration
4. Store PushSubscription in backend database
5. Backend sends notification using PushSubscription endpoint
6. Service worker receives push event and shows Notification

Using the generated Stimulus controller for Notifications, we can add a button that attempts to subscribe to Web Push.

<%= tag.button "Notifications", data: {
  controller: :notifications,
  action: "notifications#attemptToSubscribe",
  notifications_subscriptions_url_value: push_subscriptions_path,
  notifications_vapid_public_key_value: ActionPushWeb.vapid_identification.fetch(:public_key)
} %>

When clicked, this will register the service worker, ask for Notification permission, and make a POST request to push_subscriptions_path to store the PushSubscription details with Action Push Web.

The service worker is responsible for receiving Push events and displaying them with the Notification API.

It can be used to set the the app badge as well.

You can send notifications to one subscription or many using the pool.

Common arguments for notifications:

• title - The title of the notification
• body - The main content of the notification
• path - A path like /notifications to open when the notification is clicked
• badge (optional) - Sets the badge on the icon, commonly used for unread message counts
• icon (optional) - URL of an icon to be displayed in the notification

See Notification parameters

Using an ActionPushWeb::Subscription, you can build a notification and deliver it.

push_subscription = Current.user.push_subscriptions.last
push_subscription.notification(
  title: "Hello world",
  body: Random.uuid,
  path: notifications_path,
  badge: 1,
  icon: image_url("logo.png")
).deliver

You can send many notifications at once using the Pool. This uses a persistent connection to speed up delivery.

push_subscriptions = ActionPushWeb::Subscription.all

ActionPushWeb.queue({
  title: "Hello world",
  body: Random.uuid,
  path: notifications_path,
  badge: 1,
  icon: image_url("logo.png")
}, push_subscriptions)

Ensure that your operating system settings allow notifications for your browser.

Contribution directions go here.

The gem is available as open source under the terms of the MIT License.

This library is based on pushpad/web-push