Push API: the PushSubscription object explained

A "push subscription" represents a subscriber to the push notifications of a website.

In order to send push notifications to a user, a website needs to obtain a push subscription from the user's browser.

First the website calls PushManager.subscribe() or PushManager.getSubscription(), then, if the user grants permission for push notifications, the browser contacts its push service to generate a new push subscription.

Finally the push subscription is passed to the website using a JavaScript callback (a Promise is resolved) and the website frontend sends the push subscription to the backend, where the subscription is saved in a database.

Now the website can use the "push subscription" at any time to send a push notification.

In particular, the website generates a new push message, encrypts and signs it with the keys included in the push subscription, and delivers it to an HTTP endpoint using the Web Push protocol.

For more information about the workflow, you can also read this introduction in the docs.

Now that we have an overview of how a push subscription is used, we can inspect the fields of the object in more detail.

In order to generate a new push subscription you can use PushManager.subscribe(), as defined in the Push API standard, or you can use this command if you use Pushpad:

pushpad('subscribe');

Then you can inspect the PushSubscription object using this code (you can run it in the browser developer console):

navigator.serviceWorker.ready.then(function (serviceWorkerRegistration) {
  serviceWorkerRegistration.pushManager.getSubscription().then(function (subscription) {
    console.log(JSON.stringify(subscription));
  });
});

You will get a result like this:

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/dOoYD1HLqvs:APA91bGyMaIGM7i_LqIj6tbhHroQvdC3EucDJB0AYBTrjKaME5s2eEi7e7GBDPOOI5hNrJvM1eOY-5viQp0yO3naIFi8ly_W5Eci6VgMO-MHDvrIHPp1w_p7xKhRLTNMlzTj9CscdnOH",
  "expirationTime": null,
  "keys": {
    "p256dh": "BNM79uCD5T5ZmnA6NCVJ8ZZVxDU3e8Gm4Qa8CQphuZbeCYSnezvJOOAo5oOQhUAtUoFuOEvBhe2KrKnd03a8l_Q",
    "auth": "lljC-VoEkUbEYe37x21AFw"
  }
}

This is the subscription object that you usually need to store in your database and that you can use for sending the notifications.

If you are using Pushpad, the subscriptions are saved automatically in a secure database managed by Pushpad: if you want, you can open your project in the Pushpad dashboard and click Subscriptions to see them.

Let's see the meaning of the fields in more detail:

• "endpoint" is the URL that you need to contact with an HTTP POST request if you want to send a notification to that browser. Each browser generates a unique endpoint which is different for each domain. You can learn more in this post.

• "keys" are used to digitally sign the push notifications. This ensures authenticity, integrity and privacy.

• "expirationTime" is the expiration for this subscription. In practice, it is not widely used and is usually null, meaning that the subscription does not expire automatically at a given time. However the subscription will expire if the user revokes the permission and in other circumstances.