Pushpad

Getting started with web push notifications

Pushpad is a service for sending push notifications from websites and web apps. It supports the Push API (Chrome, Firefox, Edge, Opera, etc.) and APNs (Safari).

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 domain.

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:

service-worker.js
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'); });

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.");
      }
    });
  });
});

Check out the Javascript SDK reference for more information.

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.

If you are testing using Safari desktop the address must be http://localhost: do not use custom ports nor the ip address. You also need to pass hostname as an option to 'init' as described in the API reference.

A better solution would be to make the local environment look like the production one: for example add something like 127.0.0.1 example.com to /etc/hosts and use real SSL certificates (self-signed certificates don't work).

You may also want to create two separate projects on Pushpad for development and production. However make sure to associate both projects to the same sender, otherwise you may have to unsubscribe and resubscribe from browser settings.