This gem makes it possible to send push messages to web browsers from Ruby backends using the Web Push Protocol. It supports Message Encryption for Web Push to send messages securely from server to user agent.
Payload is supported by Chrome 50+, Firefox 48+, Edge 79+.
webpush Demo app here (building by Sinatra app).
Add this line to your application's Gemfile:
gem 'webpush'And then execute:
$ bundle
Or install it yourself as:
$ gem install webpush
Sending a web push message to a visitor of your website requires a number of steps:
- Your server has (optionally) generated (one-time) a set of Voluntary Application server Identification (VAPID) keys. Otherwise, to send messages through Chrome, you have registered your site through the Google Developer Console and have obtained a GCM sender id and GCM API key from your app settings.
- A
manifest.jsonfile, linked from your user's page, identifies your app settings. - Also in the user's web browser, a
serviceWorkeris installed and activated and itspushManagerproperty is subscribed to push events with your VAPID public key, with creates asubscriptionJSON object on the client side. - Your server uses the
webpushgem to send a notification with thesubscriptionobtained from the client and an optional payload (the message). - Your service worker is set up to receive
'push'events. To trigger a desktop notification, the user has accepted the prompt to receive notifications from your site.
Use webpush to generate a VAPID key that has both a public_key and private_key attribute to be saved on the server side.
# One-time, on the server
vapid_key = Webpush.generate_key
# Save these in your application server settings
vapid_key.public_key
vapid_key.private_key
# Or you can save in PEM format if you prefer
vapid_key.to_pemCheck out the Web Manifest docs for details on what to include in your manifest.json file. If using VAPID, no app credentials are needed.
{
"name": "My Website"
}For Chrome web push, add the GCM sender id to a manifest.json.
{
"name": "My Website",
"gcm_sender_id": "1006629465533"
}The file is served within the scope of your service worker script, like at the root, and link to it somewhere in the <head> tag:
<!-- index.html -->
<link rel="manifest" href="/manifest.json" />Your application javascript must register a service worker script at an appropriate scope (we're sticking with the root).
// application.js
// Register the serviceWorker script at /serviceworker.js from your server if supported
if (navigator.serviceWorker) {
navigator.serviceWorker.register('/serviceworker.js')
.then(function(reg) {
console.log('Service worker change, registered the service worker');
});
}
// Otherwise, no push notifications :(
else {
console.error('Service worker is not supported in this browser');
}The VAPID public key you generated earlier is made available to the client as a UInt8Array. To do this, one way would be to expose the urlsafe-decoded bytes from Ruby to JavaScript when rendering the HTML template. (Global variables used here for simplicity).
window.vapidPublicKey = new Uint8Array(<%= Base64.urlsafe_decode64(ENV['VAPID_PUBLIC_KEY']).bytes %>);Your application javascript uses the navigator.serviceWorker.pushManager to subscribe to push notifications, passing the VAPID public key to the subscription settings.
// application.js
// When serviceWorker is supported, installed, and activated,
// subscribe the pushManager property with the vapidPublicKey
navigator.serviceWorker.ready.then((serviceWorkerRegistration) => {
serviceWorkerRegistration.pushManager
.subscribe({
userVisibleOnly: true,
applicationServerKey: window.vapidPublicKey
});
});If you will not be sending VAPID details, then there is no need generate VAPID keys, and the applicationServerKey parameter may be omitted from the pushManager.subscribe call.
// application.js
// When serviceWorker is supported, installed, and activated,
// subscribe the pushManager property with the vapidPublicKey
navigator.serviceWorker.ready.then((serviceWorkerRegistration) => {
serviceWorkerRegistration.pushManager
.subscribe({
userVisibleOnly: true
});
});Hook into an client-side or backend event in your app to deliver a push message. The server must be made aware of the subscription. In the example below, we send the JSON generated subscription object to our backend at the "/push" endpoint with a message.
// application.js
// Send the subscription and message from the client for the backend
// to set up a push notification
$(".webpush-button").on("click", (e) => {
navigator.serviceWorker.ready
.then((serviceWorkerRegistration) => {
serviceWorkerRegistration.pushManager.getSubscription()
.then((subscription) => {
$.post("/push", { subscription: subscription.toJSON(), message: "You clicked a button!" });
});
});
});Imagine a Ruby app endpoint that responds to the request by triggering notification through the webpush gem.
# app.rb
# Use the webpush gem API to deliver a push notiifcation merging
# the message, subscription values, and vapid options
post "/push" do
Webpush.payload_send(
message: params[:message],
endpoint: params[:subscription][:endpoint],
p256dh: params[:subscription][:keys][:p256dh],
auth: params[:subscription][:keys][:auth],
vapid: {
subject: "mailto:[email protected]",
public_key: ENV['VAPID_PUBLIC_KEY'],
private_key: ENV['VAPID_PRIVATE_KEY']
},
ssl_timeout: 5, # value for Net::HTTP#ssl_timeout=, optional
open_timeout: 5, # value for Net::HTTP#open_timeout=, optional
read_timeout: 5 # value for Net::HTTP#read_timeout=, optional
)
endNote: the VAPID options should be omitted if the client-side subscription was
generated without the applicationServerKey parameter described earlier. You
would instead pass the GCM api key along with the api request as shown in the
Usage section below.
Your /serviceworker.js script may respond to 'push' events. One action it can take is to trigger desktop notifications by calling showNotification on the registration property.
// serviceworker.js
// The serviceworker context can respond to 'push' events and trigger
// notifications on the registration property
self.addEventListener("push", (event) => {
let title = (event.data && event.data.text()) || "Yay a message";
let body = "We have received a push message";
let tag = "push-simple-demo-notification-tag";
let icon = '/assets/my-logo-120x120.png';
event.waitUntil(
self.registration.showNotification(title, { body, icon, tag })
)
});Before the notifications can be displayed, the user must grant permission for notifications in a browser prompt, using something like the example below.
// application.js
// Let's check if the browser supports notifications
if (!("Notification" in window)) {
console.error("This browser does not support desktop notification");
}
// Let's check whether notification permissions have already been granted
else if (Notification.permission === "granted") {
console.log("Permission to receive notifications has been granted");
}
// Otherwise, we need to ask the user for permission
else if (Notification.permission !== 'denied') {
Notification.requestPermission(function (permission) {
// If the user accepts, let's create a notification
if (permission === "granted") {
console.log("Permission to receive notifications has been granted");
}
});
}If everything worked, you should see a desktop notification triggered via web push. Yay!
Note: if you're using Rails, check out serviceworker-rails, a gem that makes it easier to host serviceworker scripts and manifest.json files at canonical endpoints (i.e., non-digested URLs) while taking advantage of the asset pipeline.
message = {
title: "title",
body: "body",
icon: "http://example.com/icon.pn"
}
Webpush.payload_send(
endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
message: JSON.generate(message),
p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
auth: "aW1hcmthcmFpa3V6ZQ==",
ttl: 600, # optional, ttl in seconds, defaults to 2419200 (4 weeks)
urgency: 'normal' # optional, it can be very-low, low, normal, high, defaults to normal
)Webpush.payload_send(
endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
auth: "aW1hcmthcmFpa3V6ZQ=="
)VAPID details are given as a hash with :subject, :public_key, and
:private_key. The :subject is a contact URI for the application server as either a "mailto:" or an "https:" address. The :public_key and :private_key should be passed as the base64-encoded values generated with Webpush.generate_key.
Webpush.payload_send(
endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
message: "A message",
p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
auth: "aW1hcmthcmFpa3V6ZQ==",
vapid: {
subject: "mailto:[email protected]",
public_key: ENV['VAPID_PUBLIC_KEY'],
private_key: ENV['VAPID_PRIVATE_KEY']
}
)This library also supports the PEM format for the VAPID keys:
Webpush.payload_send(
endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
message: "A message",
p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
auth: "aW1hcmthcmFpa3V6ZQ==",
vapid: {
subject: "mailto:[email protected]"
pem: ENV['VAPID_KEYS']
}
)Webpush.payload_send(
endpoint: "https://fcm.googleapis.com/gcm/send/eah7hak....",
message: "A message",
p256dh: "BO/aG9nYXNkZmFkc2ZmZHNmYWRzZmFl...",
auth: "aW1hcmthcmFpa3V6ZQ==",
api_key: "<GCM API KEY>"
)see. https://github.com/zaru/web-push-sample
p256dh and auth generate sample code.
navigator.serviceWorker.ready.then(function(sw) {
Notification.requestPermission(function(permission) {
if(permission !== 'denied') {
sw.pushManager.subscribe({userVisibleOnly: true}).then(function(s) {
var data = {
endpoint: s.endpoint,
p256dh: btoa(String.fromCharCode.apply(null, new Uint8Array(s.getKey('p256dh')))).replace(/\+/g, '-').replace(/\//g, '_'),
auth: btoa(String.fromCharCode.apply(null, new Uint8Array(s.getKey('auth')))).replace(/\+/g, '-').replace(/\//g, '_')
}
console.log(data);
});
}
});
});payloads received sample code.
self.addEventListener("push", function(event) {
var json = event.data.json();
self.registration.showNotification(json.title, {
body: json.body,
icon: json.icon
});
});Bug reports and pull requests are welcome on GitHub at https://github.com/zaru/webpush.