Getting started with web push notifications

Pushpad is a service for sending push notifications from websites and web apps. It uses the Push API and works with all major browsers (Chrome, Firefox, Edge, Safari, Opera, etc.).

The following steps describe how to install Pushpad on your website. Basically they allow you to collect subscribers on your website and to install some code that will be used to display the notifications.

Your website must be served over HTTPS in order to use web push notifications.

First of all create a new sender for your website.

Then create a new project and select your sender.

After the project is created, you have to add this file to the root folder of your website:

importScripts('https://pushpad.xyz/service-worker.js');

If your web app already has a service worker, check out the serviceWorkerPath option of the init method.

Then copy and paste the following code on your website:

<script>
  (function(p,u,s,h,x){p.pushpad=p.pushpad||function(){(p.pushpad.q=p.pushpad.q||[]).push(arguments)};h=u.getElementsByTagName('head')[0];x=u.createElement('script');x.async=1;x.src=s;h.appendChild(x);})(window,document,'https://pushpad.xyz/pushpad.js');

  pushpad('init', PROJECT_ID);
</script>

You must replace PROJECT_ID with your project ID: you can find it in the project settings.

Warning: if you use different projects on the same domain, they must be associated to the same sender.

Then you can subscribe the users to notifications: choose one of the following methods to get started.

Method 1: Javascript widget

The widget is the easiest way to get started. Simply add the following code after init:

pushpad('widget');

There are many options to customize the appearance and behavior of the widget.

You can also display a subscribe button anywhere in your website with this code:

<div id="pushpad-subscribe"></div>

Method 2: Javascript SDK

The Javascript SDK gives you complete control on behavior and appearance.

If you want to display the permission prompt directly when the user enters your website, you can add this code after init:

if (window.sessionStorage.getItem('notification-status') != 'subscribed')
  pushpad('subscribe', function () { window.sessionStorage.setItem('notification-status', 'subscribed'); });

A simple call to pushpad('subscribe') would be fine, but the above code is more efficient when you include it on many pages.

If you want to display a subscribe button you can use this code:

<button id="notifications-button">Subscribe</button>

document.addEventListener('DOMContentLoaded', function () {
  document.querySelector('#notifications-button').addEventListener('click', function() {
    pushpad('subscribe', function (isSubscribed) {
      if (isSubscribed) {
        alert("Thanks! You have successfully subscribed to notifications.");
      } else {
        alert("You have blocked the notifications from browser preferences.");
      }
    });
  });
});

If you need to check if the user is subscribed to notifications or retrieve existing data associated to the push subscription you can use this code:

// reading the status can be useful in many cases (e.g. you can show or hide the subscribe button)
pushpad('status', function (isSubscribed, tags, uid) { console.log(isSubscribed, tags, uid); });

You can also build something more complex, like a custom prompt that asks users to subscribe to your notifications: this example shows how to build it using JavaScript and Tailwind CSS.

Check out the Javascript SDK reference for more information. You can also use the Javascript SDK to build custom components (e.g. using React, Vue.js, etc.).

Learn more

Check out the other documentation sections for more details: for example you can start sending the notifications or see more examples.

Working locally

The easiest solution for development is to use localhost. In that case you don't need SSL.

Another solution is to use a real domain name in the development environment. For example, if your domain is example.com, add something like 127.0.0.1 example.com to /etc/hosts, so that the domain name resolves to your local IP, and then use a real SSL certificate (self-signed certificates don't work).

On your personal computer that you use for development, while switching between different environments and projects, it may happen that you mix different senders on the same domain (e.g. localhost). This may cause some errors: in this case remove the notification permission from browser settings and then subscribe to notifications again.