Troubleshooting web push notifications

If you cannot subscribe your website users to web push notifications or you cannot send web push notifications, then you can probably fix your issue by reading the following tips.

The prompt to allow notifications doesn't show up in Chrome / Firefox / Edge / Opera

Symptoms

• You cannot subscribe to push notifications
• When you call pushpad('subscribe') from the Javascript SDK, you don't get any prompt asking whether you want to receive push notifications

Solutions

• In order to use Pushpad, your website must be served over HTTPS (otherwise you will get the error "Only secure origins are allowed"). If you are just testing you can use localhost, which doesn't require an SSL certificate.
• Ensure that you haven't blocked notifications. Near the address bar click the lock and ensure that you have Notifications: ask (or Notifications: allow)
• Open the console from the browser developer tools and see if there are any errors there.
• Make sure that the service worker is served from the root of your website (e.g. https://example.com/service-worker.js), otherwise it may not become active on some pages causing the starvation of method calls. You can inspect the path where the service worker is installed using the Chrome Developer Tools.

The prompt to allow notifications doesn't show up in Safari

Symptoms

• You cannot subscribe to push notifications with Safari
• When you are using the widget, you get an error that says that notifications are blocked from browser preferences, even if you have never blocked them
• When you call pushpad('subscribe', function (isSubscribed) {}) from the Javascript SDK, you don't see any prompt asking whether you want to receive push notifications and isSubscribed is always false

Solutions

• Starting from Safari 12.1 you cannot display the permission prompt to the user on page load, because this is blocked by Safari. You need to display the prompt (i.e. call subscribe) after an user gesture, like a click on a button. Otherwise you can use the widget.
• This indicates a problem with the push package: usually it is the signature verification that fails. Make sure that you have entered the correct APNs certificate and APNs private key in the sender settings. Also make sure that the certificate is not expired or revoked. You may also try to generate the certificate again in order to make sure that you have done the correct steps.
• Make sure that you have set the same values for the domain in the sender settings, in the Website Push ID and in the hostname option of the init method of the Javascript SDK. For example if you have set example.com as the domain in the sender settings, then the Website Push ID must be web.com.example and your init must look like pushpad('init', '123', { hostname: "example.com" }). Make sure not to mix the www and non-www version of the domain: example.com and www.example.com are not the same (by the way, both domains will support push notifications, but don't mix them in the configuration).
• Check the URL of the page where you are calling pushpad('subscribe') and make sure that the actual domain of that page is the Domain specified in the sender settings or it is included in the Additional domains in the sender settings.
• If you are testing locally on your machine, then you need to follow the steps described in Working locally

You get a Javascript error about the applicationServerKey

Symptoms

• You cannot subscribe to the notifications, even if you have granted permission
• When you try to subscribe the user to push notifications, you can see this message in the browser developer console: DOMException: Registration failed - A subscription with a different applicationServerKey (or gcm_sender_id) already exists; to change the applicationServerKey, unsubscribe then resubscribe.

Solutions

• You get this exception because you are using multiple senders with different VAPID keys on the same domain. Don't do that! You can use only one sender per domain.
• Make sure that you are using only one Pushpad project on your domain. If you are using multiple projects on the same domain that's fine, but you must make sure that they are associated to the same sender.
• You can get this error on your development machine if you use different Pushpad senders for development and production. Usually you should use the same sender and just create different projects for each environment.
• You can get this error when you are migrating to Pushpad from a different push service and you have not imported your VAPID keys.
• You can get this error if you have subscribed to push notifications a lot of time ago when Chrome did not support VAPID and used a GCM sender instead.
• In any case this exception can be fixed easily by resetting the browser subscription: go to browser preferences (or click the green lock near the address bar) and block the notifications for your domain, then allow notifications again and visit your website to subscribe to the notifications. If your users are experiencing problems with push notifications you can tell them to do the same.

The Wordpress plugin doesn't send the push notifications

Symptoms

• When you send a notification from the Wordpress plugin you get an error, but the notifications work if you send them from the Pushpad dashboard

Solutions

The Wordpress plugin cannot talk with Pushpad:

• Make sure that the access token and project ID that you have entered in the plugin settings are correct; also make sure that the access token has access to that project (you can check the projects associated to an access token from the Pushpad dashboard)
• You need to enable the cURL extension from php.ini
• Ensure that the firewall is not blocking outgoing connections to pushpad.xyz
• If the error is about SSL, you probably have to download a valid CA root certificate bundle to your server and configure PHP to use it

I get "The website has refreshed in background" instead of the actual notification

Symptoms

• You receive a notification in Chrome (Desktop or Android) with the message "The website has refreshed in background" and when you click it you get an error

Solutions

Push notifications work like this: Pushpad sends a signal to your smartphone and says that there are some unread notifications. Then your smartphone connects to Pushpad to read the new notifications and display them. However if there aren't any new notifications or if your smartphone cannot connect to Pushpad then a default notification is displayed by Chrome.

• The most likely cause, mainly if you are on a slow / unrealiable connection, is that the connection drops when your smartphone tries to connect to Pushpad. You cannot do anything about that. If this is the reason, you should usually receive the notifications when you are on a good internet connection.
• If you have set a short TTL for the notification (i.e. a few seconds) try to increase the TTL (e.g. 1 or 2 minutes at least)
• There may be other transient causes. If the error persists, you can contact support.

The notification is successfully sent but it is not displayed

Symptoms

• A notification is reported as successully sent in the Pushpad dashboard, however it is not displayed on the user device
• You send many notifications but you get zero clicks

Solutions

A web push notification is marked as successully sent when Pushpad has delivered it to the browser push service (e.g. Mozilla autopush, Google FCM, Microsoft WNS). Then the browser push service is responsible for delivering it to the end device and the user device is responsible for displaying it using the service worker.

• Make sure that the service worker is installed correctly on your website: it must be accessible at https://example.com/service-worker.js (where example.com is your website) or you must configure the serviceWorkerPath when you call the Javascript SDK init.
• Make sure that your application has registered the correct service worker: you can check which file is currently installed using the Chrome developer tools.
• There can be many reasons that make it impossible for the browser push service to deliver the notification to the user browser.

General troubleshooting: notifications don't work

If you have a problem that is not listed above you can try with the following steps in order to find the cause.

1. Are you subscribed to the push notifications?
   • You can go to Project > Subscriptions and see if your subscription is listed there
   • You can go to your website and use the pushpad('status') function of the Javascript SDK
   • Try to keep the browser developer console open while you subscribe to push notifications: are there any errors listed there?
2. If you are using a library, plugin or integration to send the notifications, then you must ensure that Pushpad receives the notifications. Send a notification, then go to Project > Notifications and check if the notification is listed there.
3. From the Pushpad dashboard, click Details near the notification. Is the notification successfully sent? Are there any errors listed there? If the counter successfully sent is equal to zero or lower than expected and there aren't any errors listed there, then you can contact support, so that we can check a more detailed log (remember to include the notification id in the ticket).
4. If the notifications are successfully sent, then you must test the reception. Open the browser tools to inspect the service worker and try to send a notification while keeping the service worker console open: are there any errors listed there?
5. Finally, you can always contact support and we'd be happy to help! Please remember to include the project id and the notification id if relevant.