Remote Notifications

In this page you'll learn how notifications are handled in your app and what are all the options at your disposal to create a great messaging experience for your users.

Requesting Permission

To enable remote notifications within your application, it's important to obtain user permissions before sending any notifications. Due to certain constraints imposed by web browsers, this permission request cannot occur automatically during page loading. Instead, it must be triggered as a direct result of a user action, such as clicking a designated button.

There are two primary methods for on-boarding users to enable remote notifications: utilizing the Dashboard's management features or manually integrating the functionality through your codebase.

When configuring a specific launch mode within the Settings > Website Push > Launch Configurator section via the Dashboard, our SDK will take care of displaying the required user interface components based on the chosen mode. Furthermore, the SDK will seamlessly handle the activation of remote notifications when deemed appropriate for the selected configuration. Lastly, make sure to include the Notificare Push CSS file which is necessary to correctly display the managed on-boarding UI.

import 'notificare-web/push/push.css';

Alternatively, should you choose to manually enable remote notifications, the responsibility falls upon you to oversee the on-boarding user interface and the entire associated process.

Enabling Notifications

In order to enable the device to receive notifications, all that you need to do is invoke a single method.

import { enableRemoteNotifications } from 'notificare-web/push';

await enableRemoteNotifications();

You can check if the user has previously enabled remote notifications.

import { hasRemoteNotificationsEnabled } from 'notificare-web/push';

const enabled = hasRemoteNotificationsEnabled();

Additionally, you can check if the user has disabled notifications in the Browser Settings.

import { getAllowedUI } from 'notificare-web/push';

const allowedUI = getAllowedUI();

Although changes only take place when the user reloads the page, you can also be notified of browser notification permission changes.

import { onNotificationSettingsChanged } from 'notificare-web/push';

onNotificationSettingsChanged((allowedUI) => {
  // more code ...
});

Disabling remote notifications

Disabling remote notifications can be achieved in the same fashion as enabling them.

import { disableRemoteNotifications } from 'notificare-web/push';

await disableRemoteNotifications();

When this method is called, we will automatically register your device to never receive remote notifications, although you will still maintain the same user profile, inbox messages and enjoy all the other services your plan supports. You can at anytime request a re-register for push notifications if you wish to.

Receiving Notifications

In order to receive notifications, it's necessary to have a service worker file available at the root directory of your website.

To simplify the process, we offer a worker file that handles incoming notifications, eliminating the need for any manual integration.

Ensure that you serve this file at https://your-website/sw.js. If you integrate this file as part of your build procedure, you can import it from the package using the example below.

import 'notificare-web/push/sw';

Alternatively, you have the option to import it directly from the CDN using the importScripts function. However, it's important to confirm that the imported version aligns with the version of your packages.

importScripts('https://cdn.notifica.re/libs/web/v3/{{version}/notificare-push-sw.js');

For more comprehensive insights into Service Workers, refer to the detailed information available here.

In order to support Web Push in iOS 16.4 or higher, it's necessary to serve a manifest file setting the display property to standalone. You can refer to the following manifest.json as a starting point for your application.

{
  "name": "Your app name",
  "short_name": "Your app name",
  "display": "standalone",
  "start_url": "/"
}

Lastly, declare your manifest in your HTML file as illustrated below.

<!DOCTYPE html>
<html>
<head>
  <link rel="manifest" href="/manifest.json" />
</head>
</html>

Note: Web Push in iOS 16.4 or higher is only available when the user adds the web app to the Home Screen.

You can find more information about Web App Manifest files here.

Listening to Received Notifications

Once you're receiving notifications in your app, we can dive deeper and fully understand how they are handled. Our library takes care of placing a notification in the Notification Center so developers will not need to take any action in order to display notifications. If you want to be notified incoming notifications, for example to add a badge to your application, you can leverage the onNotificationReceived event.

import { onNotificationReceived } from 'notificare-web/push';

onNotificationReceived((notification) => {
  // more code ...
});

Presenting notifications

A notification can be opened by either tapping the actual notification or by tapping an action inside the notification. We will emit an event in each case. To receive those events, add the following to your application.

import { onNotificationOpened, onNotificationActionOpened } from 'notificare-web/push';

onNotificationOpened((notification) => {
  // more code ...
});

onNotificationActionOpened((notification, action) => {
  // more code ...
});

To handle the events above, you can take the managed approach and use the push-ui sub-package which takes care of all the events and UI types as well as actions, or you can fully take over and present them however you prefer. However, be aware if you take the non-managed approach as you will have to deal with all aspects and types of presenting the notifications, including the events needed to show the user's engagement in our Dashboard.

The code below illustrates how this works when using the managed approach. Make sure to include the Notificare Push UI CSS file which is necessary to correctly display the managed UI.

import { onNotificationOpened, onNotificationActionOpened } from 'notificare-web/push';
import { presentNotification, presentAction } from 'notificare-web/push-ui';
import 'notificare-web/push-ui/push-ui.css';

onNotificationOpened((notification) => {
  presentNotification(notification);
});

onNotificationActionOpened((notification, action) => {
  presentAction(notification, action);
});

Additionally, when using the managed approach, you can listen to notification lifecycle events and perform any additional steps you may require.

import {
  onNotificationWillPresent,
  onNotificationPresented,
  onNotificationFinishedPresenting,
  onNotificationFailedToPresent,
  onActionWillExecute,
  onActionExecuted,
  onActionFailedToExecute,
  onCustomActionReceived,
} from 'notificare-web/push-ui';

onNotificationWillPresent((notification) => {
  // more code ...
});

onNotificationPresented((notification) => {
  // more code ...
});

onNotificationFinishedPresenting((notification) => {
  // more code ...
});

onNotificationFailedToPresent((notification) => {
  // more code ...
});

onActionWillExecute((notification, action) => {
  // more code ...
});

onActionExecuted((notification, action) => {
  // more code ...
});

onActionFailedToExecute((notification, action) => {
  // more code ...
});

onCustomActionReceived((notification, action, target) => {
  // more code ...
});

Notifications from Unknown Sources

In some apps it is possible you're also using other providers to send remote notifications, when that is the case Notificare will recognize an unknown notification and trigger an event that you can use to further handle that notification. To be notified whenever that happens, implement the following listener.

import { onUnknownNotificationReceived } from 'notificare-web/push';

onUnknownNotificationReceived((notification) => {
  // more code ...
});