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-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-push-ui module to take advantage of the managed notification UI, which simplifies implementation and ensures a consistent user experience.

To enable this functionality, include the actito-push and the actito-push-ui modules in your project's packages.json.

{
  "dependencies": {
    "cordova-plugin-actito-push": "^5.0.0",
    "cordova-plugin-actito-push-ui": "^5.0.0"
  }
}

Requirements

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

• You have successfully completed the Getting Started guide
• Android: You have set up Firebase Cloud Messaging (FCM) for your application
• iOS: You have set up APNS authentication key for your application

Notification provider environments

As described in the Environments section of the Getting Started guide, maintaining separate environments for development and production is essential. This separation becomes even more critical when implementing remote notifications.

Each environment should use its own Actito Services configuration to ensure consistent and isolated registration of push subscriptions. For example, development builds should receive notifications only from the development environment, while production builds communicate exclusively with the production environment. This approach ensures data consistency and a clean testing process.

Requesting permission

To receive remote notifications on Android, your application must request the user’s permission to display notifications. This can typically be done during the onboarding flow or at the point where notifications are first needed.

async function requestNotificationsPermission() {
  try {
    if (await ActitoPush.shouldShowPermissionRationale()) {
      await ActitoPush.presentPermissionRationale({
        title: '...',
        message: '...',
        buttonText: '...',
      });
    }

    const status = await ActitoPush.requestPermission();
    if (status === PushPermissionStatus.GRANTED) {
      // Enable remote notifications
      return;
    }

    // Unlike the method ActitoPush.checkPermissionStatus(), both iOS and Android can return permanently denied.
    if (status === PushPermissionStatus.PERMANENTLY_DENIED) {
      // TODO: Show some informational UI, educating the user to change the permission via the Settings app.
      await ActitoPush.openAppSettings();
    }
  } catch (e) {
    // Handle error
  }
}

You can also check the status of the notifications permission at any time, as illustrated below.

async function checkNotificationsPermissionStatus() {
  try {
    const status = await ActitoPush.checkPermissionStatus();
    switch (status) {
      case PushPermissionStatus.GRANTED:
        // granted
        break;
      case PushPermissionStatus.DENIED:
        // denied
        break;
      case PushPermissionStatus.PERMANENTLY_DENIED: {
        // Permanently denied status can only be returned in iOS and Android 12 or lower.
        // Devices with Android 13 and up will return granted or denied.
        break;
      }
    }
  } catch (e) {
    // Handle error
  }
}

note

• The examples above use the convenience methods available in the ActitoPush plugin to handle the bridge into native permission. You can use any other plugin or implement the bridge yourself. The focus of the examples is guiding you on the necessary permission and recommended upgrade path.
• It is recommended to request notification permission during onboarding or at a time when the value of notifications is clear to the user.
• Always handle the case where the user denies permission gracefully.

Enabling remote notifications

Once the necessary permissions are granted, you can enable remote notifications through the Actito SDK:

await ActitoPush.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:

// Check if the user has previously enabled remote notifications.
await ActitoPush.hasRemoteNotificationsEnabled();

// Check if the device is allowed to receive remote notifications.
await ActitoPush.allowedUI();

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:

await ActitoPush.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

Before you can start receiving push notifications, you will need to set up the native counterparts of your app.

For iOS, to handle all types of notifications, you need to make sure your app is declaring the following permissions in your app's Info.plist file.

This can be done by adding the following to your config.xml:

<platform name="ios">
  <config-file target="*-Info.plist" parent="NSCameraUsageDescription">
      <string>YOUR_RATIONALE</string>
  </config-file>

  <config-file target="*-Info.plist" parent="NSPhotoLibraryUsageDescription">
      <string>YOUR_RATIONALE</string>
  </config-file>
</platform>

For Android, 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.

A notification can be opened by either tapping the actual notification or by tapping an action inside the notification. In each case, we will emit event. Be sure to register your listeners during app initialization to avoid missing events, especially during a cold launch.

ActitoPush.onNotificationOpened(async (notification) => {
  await ActitoPushUI.presentNotification(notification);
});

ActitoPush.onNotificationActionOpened(async (notification, action) => {
  await ActitoPushUI.presentAction(notification, action);
});

Managed vs. Manual handling

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

• Managed Approach (Recommended) — Include and use the actito-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.

Displaying lock screen media

To display rich notifications — such as lock screen media or dynamically updated content — your app must include a Notification Service Extension (NSE). This extension allows the system to process incoming notifications before they are shown to the user, enabling Actito to attach images or other media to your messages.

You can find detailed setup instructions in the Notification Service Extension guide.