Home

Awesome

<h1 align="center">web-push</h1>

Build Status

Why

Web push requires that push messages triggered from a backend be done via the Web Push Protocol and if you want to send data with your push message, you must also encrypt that data according to the Message Encryption for Web Push spec.

This module makes it easy to send messages and will also handle legacy support for browsers relying on GCM for message sending / delivery.

Install

Installation is simple, just install via npm.

npm install web-push --save

Usage

The common use case for this library is an application server using a GCM API key and VAPID keys.

const webpush = require('web-push');

// VAPID keys should be generated only once.
const vapidKeys = webpush.generateVAPIDKeys();

webpush.setGCMAPIKey('<Your GCM API Key Here>');
webpush.setVapidDetails(
  'mailto:example@yourdomain.org',
  vapidKeys.publicKey,
  vapidKeys.privateKey
);

// This is the same output of calling JSON.stringify on a PushSubscription
const pushSubscription = {
  endpoint: '.....',
  keys: {
    auth: '.....',
    p256dh: '.....'
  }
};

webpush.sendNotification(pushSubscription, 'Your Push Payload Text');

Using VAPID Key for applicationServerKey

When subscribing to push messages, you'll need to pass your VAPID key, which you can do like so:

registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: '<Your Public Key from generateVAPIDKeys()>'
});

Command Line

You can install web-push globally and use it for sending notifications and / or generating VAPID keys.

Install like so:

npm install web-push -g

Then you can run the following commands:

Usage:

  web-push send-notification --endpoint=<url> [--key=<browser key>] [--auth=<auth secret>] [--payload=<message>] [--encoding=<aesgcm | aes128gcm>] [--ttl=<seconds>] [--vapid-subject=<vapid subject>] [--vapid-pubkey=<public key url base64>] [--vapid-pvtkey=<private key url base64>] [--proxy=<http proxy uri>] [--gcm-api-key=<api key>]

  web-push generate-vapid-keys [--json]

Example of send notification:

  > web-push generate-vapid-keys --json
  > {"publicKey":"BGtkbcjrO12YMoDuq2sCQeHlu47uPx3SHTgFKZFYiBW8Qr0D9vgyZSZPdw6_4ZFEI9Snk1VEAj2qTYI1I1YxBXE","privateKey":"I0_d0vnesxbBSUmlDdOKibGo6vEXRO-Vu88QlSlm5j0"}

The subscription value:

  { 
    "endpoint": "https://fcm.googleapis.com/fcm/send/d61c5u920dw:APA91bEmnw8utjDYCqSRplFMVCzQMg9e5XxpYajvh37mv2QIlISdasBFLbFca9ZZ4Uqcya0ck-SP84YJUEnWsVr3mwYfaDB7vGtsDQuEpfDdcIqOX_wrCRkBW2NDWRZ9qUz9hSgtI3sY", 
    "expirationTime": null, 
    "keys": { 
      "p256dh": "BL7ELU24fJTAlH5Kyl8N6BDCac8u8li_U5PIwG963MOvdYs9s7LSzj8x_7v7RFdLZ9Eap50PiiyF5K0TDAis7t0", 
      "auth": "juarI8x__VnHvsOgfeAPHg" 
    } 
  }

The command example:

  web-push send-notification  \
  --endpoint=https://fcm.googleapis.com/fcm/send/d61c5u920dw:APA91bEmnw8utjDYCqSRplFMVCzQMg9e5XxpYajvh37mv2QIlISdasBFLbFca9ZZ4Uqcya0ck-SP84YJUEnWsVr3mwYfaDB7vGtsDQuEpfDdcIqOX_wrCRkBW2NDWRZ9qUz9hSgtI3sY \
  --key=BL7ELU24fJTAlH5Kyl8N6BDCac8u8li_U5PIwG963MOvdYs9s7LSzj8x_7v7RFdLZ9Eap50PiiyF5K0TDAis7t0 \
  --auth=juarI8x__VnHvsOgfeAPHg \
  --vapid-subject=mailto:example@qq.com \
  --vapid-pubkey=BGtkbcjrO12YMoDuq2sCQeHlu47uPx3SHTgFKZFYiBW8Qr0D9vgyZSZPdw6_4ZFEI9Snk1VEAj2qTYI1I1YxBXE \
  --vapid-pvtkey=I0_d0vnesxbBSUmlDdOKibGo6vEXRO-Vu88QlSlm5j0 \
  --payload=Hello

API Reference

sendNotification(pushSubscription, payload, options)

const pushSubscription = {
  endpoint: '< Push Subscription URL >',
  keys: {
    p256dh: '< User Public Encryption Key >',
    auth: '< User Auth Secret >'
  }
};

const payload = '< Push Payload String >';

const options = {
  gcmAPIKey: '< GCM API Key >',
  vapidDetails: {
    subject: '< \'mailto\' Address or URL >',
    publicKey: '< URL Safe Base64 Encoded Public Key >',
    privateKey: '< URL Safe Base64 Encoded Private Key >'
  },
  timeout: <Number>
  TTL: <Number>,
  headers: {
    '< header name >': '< header value >'
  },
  contentEncoding: '< Encoding type, e.g.: aesgcm or aes128gcm >',
  urgency:'< Default is "normal" >',
  topic:'< Use a maximum of 32 characters from the URL or filename-safe Base64 characters sets. >',

  proxy: '< proxy server options >',
  agent: '< https.Agent instance >'
}

webpush.sendNotification(
  pushSubscription,
  payload,
  options
);

Note: sendNotification() you don't need to define a payload, and this method will work without a GCM API Key and / or VAPID keys if the push service supports it.

Input

Push Subscription

The first argument must be an object containing the details for a push subscription.

The expected format is the same output as JSON.stringify'ing a PushSubscription in the browser.

Payload

The payload is optional, but if set, will be the data sent with a push message.

This must be either a string or a node Buffer.

Note: In order to encrypt the payload, the pushSubscription must have a keys object with p256dh and auth values.

Options

Options is an optional argument that if defined should be an object containing any of the following values defined, although none of them are required.

Note: As of this writing, if a push notification request contains a VAPID subject referencing an https://localhost URI (set either using the options argument or via the global setVapidDetails() method), Safari's push notification endpoint rejects the request with a BadJwtToken error.

Returns

A promise that resolves if the notification was sent successfully with details of the request, otherwise it rejects.

In both cases, resolving or rejecting, you'll be able to access the following values on the returned object or error.

<hr />

generateVAPIDKeys()

const vapidKeys = webpush.generateVAPIDKeys();

// Prints 2 URL Safe Base64 Encoded Strings
console.log(vapidKeys.publicKey, vapidKeys.privateKey);

Input

None.

Returns

Returns an object with publicKey and privateKey values which are URL Safe Base64 encoded strings.

Note: You should create these keys once, store them and use them for all future messages you send.

<hr />

setGCMAPIKey(apiKey)

webpush.setGCMAPIKey('Your GCM API Key');

Input

This method expects the GCM API key that is linked to the gcm_sender_id in your web app manifest.

You can use a GCM API Key from the Google Developer Console or the Cloud Messaging tab under a Firebase Project.

Returns

None.

<hr />

setVapidDetails(subject, publicKey, privateKey)

webpush.setVapidDetails(
  'mailto:user@example.org',
  process.env.VAPID_PUBLIC_KEY,
  process.env.VAPID_PRIVATE_KEY
);

Globally sets the application's VAPID subject, public key, and private key, to be used in subsequent calls to sendNotification() and generateRequestDetails() that don't specifically override them in their options argument.

Input

The setVapidDetails method expects the following input:

Returns

None.

<hr />

encrypt(userPublicKey, userAuth, payload, contentEncoding)

const pushSubscription = {
  endpoint: 'https://....',
  keys: {
    p256dh: '.....',
    auth: '.....'
  }
};
webPush.encrypt(
  pushSubscription.keys.p256dh,
  pushSubscription.keys.auth,
  'My Payload',
  'aes128gcm'
)
.then(encryptionDetails => {

});

Encrypts the payload according to the Message Encryption for Web Push standard.

(sendNotification will automatically encrypt the payload for you, so if you use sendNotification you don't need to worry about it).

Input

The encrypt() method expects the following input:

Returns

This method returns an object with the following fields:

<hr />

getVapidHeaders(audience, subject, publicKey, privateKey, contentEncoding, expiration)

const parsedUrl = url.parse(subscription.endpoint);
const audience = parsedUrl.protocol + '//' +
  parsedUrl.hostname;

const vapidHeaders = vapidHelper.getVapidHeaders(
  audience,
  'mailto: example@web-push-node.org',
  vapidDetails.publicKey,
  vapidDetails.privateKey,
  'aes128gcm'
);

The getVapidHeaders() method will take in the values needed to create an Authorization and Crypto-Key header.

Input

The getVapidHeaders() method expects the following input:

Returns

This method returns an object with the following fields:

<hr />

generateRequestDetails(pushSubscription, payload, options)

const pushSubscription = {
  endpoint: '< Push Subscription URL >';
  keys: {
    p256dh: '< User Public Encryption Key >',
    auth: '< User Auth Secret >'
  }
};

const payload = '< Push Payload String >';

const options = {
  gcmAPIKey: '< GCM API Key >',
  vapidDetails: {
    subject: '< \'mailto\' Address or URL >',
    publicKey: '< URL Safe Base64 Encoded Public Key >',
    privateKey: '< URL Safe Base64 Encoded Private Key >',
  }
  TTL: <Number>,
  headers: {
    '< header name >': '< header value >'
  },
  contentEncoding: '< Encoding type, e.g.: aesgcm or aes128gcm >',
  urgency:'< Default is normal "Defult" >',
  topic:'< Use a maximum of 32 characters from the URL or filename-safe Base64 characters sets. >',
  proxy: '< proxy server options >'
}

try {
  const details = webpush.generateRequestDetails(
    pushSubscription,
    payload,
    options
  );
} catch (err) {
  console.error(err);
}

Note: When calling generateRequestDetails() the payload argument does not need to be defined, passing in null will return no body and exclude any unnecessary headers. Headers related to the GCM API Key and / or VAPID keys will be included if supplied and required.

Input

Push Subscription

The first argument must be an object containing the details for a push subscription.

The expected format is the same output as JSON.stringify'ing a PushSubscription in the browser.

Payload

The payload is optional, but if set, will be encrypted and a Buffer will be returned via the payload parameter.

This argument must be either a string or a node Buffer.

Note: In order to encrypt the payload, the pushSubscription must have a keys object with p256dh and auth values.

Options

Options is an optional argument that if defined should be an object containing any of the following values defined, although none of them are required.

Returns

An object containing all the details needed to make a network request, the object will contain:

<hr />

Browser Support

<table> <thead> <tr> <th><strong>Browser</strong></th> <th width="130px"><strong>Push without Payload</strong></th> <th width="130px"><strong>Push with Payload</strong></th> <th width="130px"><strong>VAPID</strong></th> <th><strong>Notes</strong></th> </tr> </thead> <tbody> <tr> <td>Chrome</td> <!-- Push without payloads support--> <td>✓ v42+</td> <!-- Push with payload support --> <td>✓ v50+</td> <!-- VAPID Support --> <td>✓ v52+</td> <td>In v51 and less, the `gcm_sender_id` is needed to get a push subscription.</td> </tr> <tr> <td>Edge</td> <!-- Push without payloads support--> <td>✓ v17+ (April 2018)</td> <!-- Push with payload support --> <td>✓ v17+ (April 2018)</td> <!-- VAPID Support --> <td>✓ v17+ (April 2018)</td> <td></td> </tr> <tr> <td>Firefox</td> <!-- Push without payloads support--> <td>✓ v44+</td> <!-- Push with payload support --> <td>✓ v44+</td> <!-- VAPID Support --> <td>✓ v46+</td> <td></td> </tr> <tr> <td>Opera</td> <!-- Push without payloads support--> <td>✓ v39+ <strong>*</strong></td> <!-- Push with payload support --> <td>✓ v39+ <strong>*</strong></td> <!-- VAPID Support --> <td>✗</td> <td> <strong>*</strong> Opera supports push on Android but not on desktop. <br /> <br /> The `gcm_sender_id` is needed to get a push subscription. </td> </tr> <tr> <td>Safari</td> <!-- Push without payloads support--> <td>✓ v16+ </td> <!-- Push with payload support --> <td>✓ v16+</td> <!-- VAPID Support --> <td>✓ v16+</td> <td>Safari 16 in macOS 13 or later</td> </tr> <tr> <td>Samsung Internet Browser</td> <!-- Push without payloads support--> <td>✓ v4.0.10-53+</td> <!-- Push with payload support --> <td>✓ v5.0.30-40+</td> <!-- VAPID Support --> <td>✗</td> <td>The `gcm_sender_id` is needed to get a push subscription.</td> </tr> </tbody> </table>

Help

MDN

There's an example on MDN.

Also, the Service Worker Cookbook is full of Web Push examples using this library.

Running tests

Prerequisites:

To run tests:

npm test
<p align="center"> <a href="https://www.npmjs.com/package/web-push"> <img src="https://nodei.co/npm/web-push.svg?downloads=true" /> </a> </p>