Standard

Remote notifications allow your application to receive messages from Actito in real time, even when the app is not active. To enable this functionality, include the actito-web/push module in your project. This module provides all the components necessary to register the push subscription and handle incoming notifications. You may implement a custom user interface to present notifications. However, we recommend including the actito-web/push-ui module to take advantage of the managed notification UI, which simplifies implementation and ensures a consistent user experience.

Requirements

Before getting started with this module, ensure that the following steps have been completed:

• You have successfully completed the Getting Started guide
• You have created and setup the [WebPush service] in your Actito app

Service Worker and Web Push Requirements

To enable your website to receive push notifications, a Service Worker file must be available at the root of your domain. The Service Worker is responsible for handling incoming notifications in the background, even when the web page is not actively open.

To simplify implementation, the Actito Web SDK provides a prebuilt Service Worker that manages incoming notifications automatically — no manual integration required.

Ensure this file is served at:

https://your-website/sw.js

If you integrate the Service Worker as part of your build process, you can import it directly from the package as shown below:

import 'actito-web/push/sw'

Alternatively, you may import it from the Actito CDN using the importScripts function. When doing so, make sure that the imported version matches the SDK version used in your project.

importScripts('https://cdn-mobile.actito.com/libs/web/v5/{{version}}/actito-push-sw.js')

note

Mismatched versions between your SDK and the Service Worker file may lead to unexpected behavior when handling push notifications.

For more information on Service Workers and their lifecycle, refer to the MDN Service Worker API documentation.

Requesting Permission

To enable remote notifications in your web application, you must first obtain the user’s consent before sending any notifications. Due to browser security policies, this permission request cannot occur automatically during page load. It must be initiated as a direct result of a user action, such as clicking a button or interacting with a prompt within your website.

There are two primary approaches for onboarding users to enable remote notifications: you can either use a managed experience configured by Actito Support, or implement the functionality manually within your application.

When your account is configured with a specific launch mode, the SDK will automatically display the appropriate user interface components based on that configuration. It will also handle the activation of remote notifications when conditions are met, ensuring a smooth and compliant onboarding experience.

note

To update your launch mode or adjust your website’s onboarding flow, you can change your settings in your Actito app.

If your configuration uses the managed onboarding UI, make sure to include the corresponding CSS file in your project:

import 'actito-web/push/push.css'

Alternatively, if you prefer to manually handle the remote notification onboarding process, your application is responsible for managing the user interface and permission workflow — including when and how users are prompted to enable notifications.

Enabling Remote Notifications

You can enable remote notifications through the Actito SDK:

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

await enableRemoteNotifications();

After enabling, the SDK will register the device for notifications with Actito.

You can check the user’s current enrollment and permission status using:

import { hasRemoteNotificationsEnabled, getAllowedUI } from 'actito-web/push';

// Check if the user has previously enabled remote notifications.
const enabled = hasRemoteNotificationsEnabled();

// Check if the device is allowed to receive remote notifications.
const allowedUI = getAllowedUI();

These checks can help you update your app’s UI to reflect the user’s notification status or guide them to re-enable permissions if needed.

Disabling Remote Notifications

If the user chooses to stop receiving notifications, you can disable them programmatically:

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

await disableRemoteNotifications();

This action unregisters the device from receiving further remote notifications. It is recommended to provide a clear opt-out option in your app’s settings to comply with privacy and consent requirements.

Handling Remote Notifications

Notifications can be opened in two ways — by clicking the notification itself or by selecting an action button within it. In both cases, the SDK emits an event that your application can listen for and handle accordingly.

The example below demonstrates how to handle these events using the managed approach, which leverages the actito-web/push-ui module to automatically present notifications and actions with a consistent, prebuilt user interface.

Make sure to include the Actito Push UI CSS file to ensure the managed UI is displayed correctly.

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

// Handle notification opened
onNotificationOpened((notification) => {
  // Using managed approach to display notification UI
  presentNotification(notification);
});

// Handle notification action opened
onNotificationActionOpened((notification, action) => {
  // Using managed approach to display action UI
  presentAction(notification, action);
});

note

If your application needs to support Map notifications, you must configure a Google Maps API key as outlined in the Google Maps API Key guide.

Managed vs. Manual Handling

You can handle these notification events in one of two ways:

• Managed Approach (Recommended) — Include and use the actito-web/push-ui module to display notifications, actions, and track their engagement. This approach ensures consistency, proper event tracking, and integration with Actito.
• Manual Approach — Implement your own notification presentation logic. This provides full control over the UI and behavior but requires handling all notification types, user interactions, and event reporting manually.

Important

If you choose the manual approach, you are responsible for managing the full notification lifecycle, including engagement tracking required for analytics and reporting.

Supporting Web Push on iOS 16.4 and Later

To support Web Push notifications on iOS 16.4 or later, your application must serve a Web App Manifest file with the display property set to standalone. This enables the web app to function as an installable Progressive Web App (PWA) that can receive notifications when added to the user’s Home Screen.

Below is an example manifest configuration:

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

Include your manifest file in the HTML <head> section as follows:

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

note

Web Push notifications on iOS 16.4 or later are available only when the user adds your web app to their Home Screen.

For additional information about Web App Manifests, refer to the MDN Web App Manifest documentation.