Push notification integration

A push notification is an alert that appears on the user’s screen when an important update occurs. Push notifications can be received even when your web page is not currently open in the user’s browser. Push notifications are a valuable way to provide your users with time-sensitive and relevant content or to re-engage them with your site. This reference article covers how to integrate Braze web push with the Braze SDK.

Refer to our push best practices for more resources.

Web push notifications are implemented using the W3C push standard, which most major browsers support.

For more information on the push protocol standards and browser support, you can review resources from Apple Mozilla and Microsoft

Integration

Step 1: Configure your site’s service worker

• If you don’t already have a service worker, create a new file named service-worker.js with the following snippet, and place it in the root directory of your website.
• Otherwise, if your site already registers a service worker, add the following snippet to the service worker file, and set the manageServiceWorkerExternally initialization option to true when initializing the Web SDK.

If your service worker filename is not service-worker.js, you must use the serviceWorkerLocation initialization option.

What if I can’t register a service worker in the root directory?

By default, a service worker can only be used within the same directory it is registered in. For example, if your service worker file exists in /assets/service-worker.js, it would only be possible to register it within example.com/assets/* or a subdirectory of the assets folder, but not on your homepage (example.com/). For this reason, it is recommended to host and register the service worker in the root directory (such as https://example.com/service-worker.js).

If you cannot register a service worker in your root domain, an alternative approach is to use the Service-Worker-Allowed HTTP header when serving your service worker file. By configuring your server to return Service-Worker-Allowed: / in the response for the service worker, this will instruct the browser to broaden the scope and allow it to be used from within a different directory.

Can I create a service worker using a Tag Manager?

No, service workers must be hosted on your website’s server and can’t be loaded via Tag Manager.

Step 2: Browser registration

For a browser to receive push notifications, you must register it for push by calling braze.requestPushPermission(). This will immediately request push permission from the user.

If you wish to show your own push-related UI to the user before requesting push permission (known as a soft push prompt), you can test to see if push is supported in the user’s browser with braze.isPushSupported(). Refer to the soft push prompt example using in-app messages.

If you wish to unsubscribe a user, you can do so by calling braze.unregisterPush().

Step 3: Configure Safari push (optional)

If you wish to support push notifications for Safari on Mac OS X, follow these additional instructions:

• Generate a safari push certificate following the Registering with Apple instructions.
• In the Braze dashboard, on the Settings page (where your API keys are located), select your Web app. Click Configure Safari Push and follow the instructions, uploading the push certificate you just generated.
• When you call braze.initialize, supply the optional safariWebsitePushId configuration option with the website push ID you used when generating your Safari push certificate. For example braze.initialize('YOUR-API-KEY', {safariWebsitePushId: 'web.com.example.domain'})

Safari Mobile push

Safari 16.4+ on iOS and iPadOS supports web push for apps that have been added to the homescreen and have a Web Application Manifest file. After you have completed the steps to integrate web push notifications, you can provide support for mobile push for Safari as well.

To support mobile Safari web push, follow our guide here.

Soft push prompt

A soft push prompt (also known as a “push primer”) helps optimize your opt-in rate when it comes to asking for permission.

Visit Soft push prompt to learn more about setting up a soft push prompt.

HTTPS requirement

Web standards require that the domain requesting push notification permission be secure.

What defines a secure site?

A site is deemed secure if it matches one of the following secure origin patterns:

• (https, , *)
• (wss, *, *)
• (, localhost, )
• (, .localhost, *)
• (, 127/8, )
• (, ::1/128, *)
• (file, *, —)
• (chrome-extension, *, —)

This security requirement in the open standards specification that Braze Web push is built on prevents man-in-the-middle attacks.

What if a secure site is not available?

While industry best practice is to make your whole site secure, customers who cannot secure their site domain can work around the requirement by using a secure modal. Read more in our guide to using Alternate push domain or view a working demo.

Service worker advanced settings

Our service worker file will automatically call skipWaiting upon install. If you’d like to avoid this, add the following code to your service worker file, preceding importing Braze:

Troubleshooting

I followed the integration instructions, but I’m still not receiving any push notifications.

• Web push notifications require that your site be HTTPS.
• Not all browsers can receive push messages. Ensure that braze.isPushSupported() returns true in the browser.
• If a user has denied a site push access, they won’t be prompted for permission again unless they remove the denied status from their browser preferences.