🌐 Web Push

Web Push Notifications allow you to display native-like notifications to users through your website/web app, even when they’re not on your website.

Web push notifications look almost identical to native notifications on the device. However, they require the user to opt-in from their browser when they are on your website/front-end.

Not to be confused with Mobile Push notifications that are truly native (delivered from installed apps), or In-App Notifications that are displayed inside your UI, e.g. inside a bell icon or webpage.

Pros:

• Native-like notifications
• No need to install a full-fledged app

Cons:

• Requires explicit user opt-in
• Apple is not a fan of web push notifications

Supported Browsers

Minimum Browser Versions:

• Chrome v20 (2012)
• Safari 7 (2013)
• Edge v14 (2016)
• Firefox 22 (2013)
• Opera 23 (2014)
• Chrome Android v42 (2015)
• Firefox Android v22 (2013)
• Opera Android v29 (2015)
• Safari iOS v16.4 (2023)
• Samsung Internet v4 (2016)
• WebView Android: Not Supported.

Overview

Web push notifications rely on a service worker, a script that runs in the background of a user’s browser. This allows it to receive and display notifications even when your website isn’t open.

When a user grants permission for notifications, the service worker is registered, and a unique push subscription is created for them. This subscription acts as the address for sending notifications.

The process also involves VAPID (Voluntary Application Server Identification) keys. These keys securely identify your application to the browser’s push service, ensuring that notifications are coming from a legitimate source.

NotificationAPI abstracts away all this complexity. Our SDKs handle the service worker, manage push subscriptions, and secure communications with VAPID keys automatically.

The setup process looks like this:

1. Create NotificationAPI Account
2. Implement the Frontend SDK
3. Set Up the Service Worker
4. Request and Provide Permission
5. Send Notifications from the Backend

Step 1: Create NotificationAPI Account

Make sure you have a NotificationAPI account and grab your Client ID.

Step 2: Implement the Frontend SDK

Our front-end SDKs will handle requesting user permission, syncing

npm install @notificationapi/react --legacy-peer-deps
# or
# yarn add @notificationapi/react
# or
# pnpm add @notificationapi/react

import { NotificationAPIProvider } from '@notificationapi/react';

<App>
  <NotificationAPIProvider
    clientId="abc123"
    userId="user@example.com"
    customServiceWorkerPath="service/notificationapi-service-worker.js"
  >
    {/* routes where you want to request notification permission */}
  </NotificationAPIProvider>
</App>;

Step 3: Set up Service Worker

The service worker manages background tasks and is essential for receiving push notifications. It should be publicly accessible, so it usually goes in the public folder of your web application.

1. Download notificationapi-service-worker.js
2. Place the file in the public folder of your web application. It should be accessible at https://yourdomain.com/notificationapi-service-worker.js.

If the service worker is not at {website}/notificationapi-service-worker.js, specify its path using the customServiceWorkerPath parameter during SDK initialization.

For example, if service worker accessible at https://yourdomain.com/service/myworker.js, then the customServiceWorkerPath should be /service/myworker.js.

Step 4: Request and Provide Permission

With our SDK and service worker in place, the notifications are ready to flow, however, you need to get the user’s permission.

There are multiple options to prompt the user for permissions:

Option 1: Programmatically

You can use NotificationAPIContext and the setWebPushOptIn method to programmatically request permission.

const AskforPerm: React.FC = () => {
  const notificationapi = NotificationAPIProvider.useNotificationAPIContext();

  return (
    <Button
      onClick={() => {
        notificationapi.setWebPushOptIn(true);
      }}
    >
      Click to pop up the permission prompt
    </Button>
  );
};

export default AskforPerm;

Option 2: Pre-built UIs

If you are using our pre-built React UIs, it will automatically display an opt-in message inside the in-app notifications screen and the user preference screen.

Step 5: Trigger Notifications from the Backend

Given the frontend is set up to receive notifications and the user has granted permission, you can now trigger them from your backend.

Important Features

• Visual editor
• Supports all devices
• Supports image and icon
• Supports redirecting the user to a URL when they click on the notification

Tracking and Analytics

NotificationAPI automatically tracks web push notification metrics:

• Delivery: Successfully delivered to browser
• Opens and Clicks: When users view and click notifications (Coming soon)

View all analytics in your dashboard under Logs and Insights.

Events Webhook

Following are the events that you can receive via Events Webhook:

• Failures
• Unsubscribes

Schematic Diagram

Below is a detailed schematic that breaks down each step:

Frequently Asked Questions (FAQs)

Why I see this message: WEB_PUSH delivery is activated, but the user’s webPushTokens is not provided. Discarding WEB_PUSH?

It means that you have done Step 1 and Step 5 correctly, but you probably have not implemented our frontend SDK correctly (Step 2), or you have not set up the service worker (Step 3), or your user is not opted in for receiving web push notification (Step 4).

Why can I not see the browser prompt in Step 4?

If you do not see the message in the NotificationAPI component, that browser has already opted in for that user.

Reset Chrome on Desktop

1. Click the “View Site Information” icon next to your URL in the Chrome browser.
2. Under “Notifications”, click the Reset permission button.

Reset Firefox on Desktop

1. Click the “i” or “lock” icon beside your site URL.
2. Next to Receive Notifications under Permissions, select the “X” button next to Allowed

How can I make sure if the Service Worker has been initialized properly?

1. Follow the Step 3

2. Open the built-in developer tools for the site (F12 on PC or fn + F12 on Mac), then go to Applications >> Service workers. If the service worker has been initialized, it would look something like this:

3. If notificationapi-service-worker.js (Service Worker) doesn’t show up, that means the service worker is not there inside the public folder. Please make sure that it is placed inside the public folder. Or pass the address to the publicly available file using customServiceWorkerPath

How to check Notification Settings on macOS and Windows?

It’s important to verify your notification settings at your operating system level as well to ensure proper functionality.

macOS

1. Go to System Preferences > Notifications.
2. Find your app (chrome, firefox, safari, etc…) in the list and ensure notifications are enabled.

Windows

1. Open Settings > System > Notifications.
2. Ensure to enable Notifications for proper functionality.