Advanced

The following article covers advanced features available in the Actito SDK.

These topics are optional and can be adopted selectively based on your application’s requirements. You can safely skip any sections that are not relevant to your use case or implementation strategy.

Receiving Push Events

When using the Remote Notifications module, you can listen to a series of push events emitted by the SDK during notification delivery and interaction lifecycle.

These events allow you to extend the default behavior — for example, tracking delivery analytics, responding to user interactions, or handling custom payloads.

To do this, you can listen to the following events as needed:

ActitoPush.onNotificationInfoReceived(({ notification, deliveryMechanism }) => { });

ActitoPush.onSystemNotificationReceived((notification) => { });

ActitoPush.onUnknownNotificationReceived((notification) => { });

ActitoPush.onNotificationOpened((notification) => { });

ActitoPush.onNotificationActionOpened(({ notification, action }) => { });

ActitoPush.onUnknownNotificationOpened((notification) => { });

ActitoPush.onUnknownNotificationActionOpened((data) => { });

ActitoPush.onNotificationSettingsChanged((granted) => { });

ActitoPush.onSubscriptionChanged((subscription) => { });

ActitoPush.onShouldOpenNotificationSettings((notification) => { });

ActitoPush.onFailedToRegisterForRemoteNotifications((error) => { });

Push Events

• onNotificationInfoReceived: Called when a push notification is received.

ActitoPush.onNotificationInfoReceived(({ notification, deliveryMechanism }) => {
    console.log(`Notification received: ${notification.id} via ${deliveryMechanism}`);
  }
);

• onSystemNotificationReceived: Called when a custom system notification is received.

ActitoPush.onSystemNotificationReceived((notification) => {
  console.log(`System notification received: ${notification.id}`);
});

• onUnknownNotificationReceived: Called when an unknown type of notification is received.

ActitoPush.onUnknownNotificationReceived((notification) => {
  console.log(`Unknown notification received`);
});

• onNotificationOpened: Called when a push notification is opened by the user.

ActitoPush.onNotificationOpened(async (notification) => {
  console.log(`Notification opened: ${notification.id}`);

  // Using managed approach to present notification
  await ActitoPushUI.presentNotification(notification);
});

• onUnknownNotificationOpened: Called when an unknown push notification is opened by the user.

ActitoPush.onUnknownNotificationOpened((notification) => {
  console.log(`Unknown notification opened`);
});

• onNotificationActionOpened: Called when a push notification action is opened by the user.

ActitoPush.onNotificationActionOpened(async ({ notification, action }) => {
    console.log(`Action opened: ${action.type} associated with a notification ${notification.id}`);

    // Using managed approach to present action associated with a notification
    await ActitoPushUI.presentAction(notification, action);
  }
);

• onUnknownNotificationActionOpened: Called when an unknown push notification action is opened by the user.

ActitoPush.onUnknownNotificationActionOpened((data) => {
  console.log(`Action opened associated with an unknown notification`);
});

• onNotificationSettingsChanged: Called when the notification settings are changed.

ActitoPush.onNotificationSettingsChanged((granted) => {
  console.log(`Notification settings changed. Granted: ${granted}`);
});

• onSubscriptionChanged: Called when the device's push subscription changes.

ActitoPush.onSubscriptionChanged((subscription) => {
  console.log(`Subscription updated: ${subscription?.token}`);
});

• onShouldOpenNotificationSettings: Called when a notification prompts the app to open its settings screen.

ActitoPush.onShouldOpenNotificationSettings((notification) => {
  console.log(`Should open app settings screen`);
});

• onFailedToRegisterForRemoteNotifications: Called when the app encounters an error during the registration process for remote notifications.

ActitoPush.onFailedToRegisterForRemoteNotifications((error) => {
  console.log(`Failed to register for remote notifications: ${error}`);
});

Notification Service Extension

Starting with iOS 10, Apple introduced the Notification Service Extension, which allows apps to process incoming push notifications before they are displayed to the user.

By implementing this extension, you can:

• Enrich notifications with rich media (images, videos, audio).
• Modify notification content dynamically before display.
• Perform custom client-side processing of push messages.

This guide walks you through creating and configuring a Notification Service Extension to enhance your notification experience.

Adding a Notification Service Extension

To make use of this feature you need to set the following in your app.json:

{
  "expo": {
    // more code...

    "plugins": [
      [
        "react-native-actito-push",
        {
          "ios": {
            "useNotificationServiceExtension": true,

            // Deployment target matching your application
            "deploymentTarget": "13.4"
          }
        }
      ]
    ]
  }
}

Once your implementation is complete, you can include media attachments in your notifications by:

• Uploading an image in the Lock Screen Media field when composing a message in the dashboard.
• Including the attachments property in your notification payload when sending via the REST API.

Important

To ensure reliable delivery, keep media files below 300 KB. iOS allows limited time for the extension to download attachments, and larger files may not complete in time on slow networks.

Configuring App Transport Security (optional)

Since the Notification Service Extension runs as a separate target, it maintains its own Info.plist configuration.

By default, iOS blocks non-secure (HTTP) network requests in extensions. If your lock screen media is hosted over an insecure protocol (http://), you must declare an App Transport Security exception in the extension’s Info.plist.

Notification lifecycle

When using the Push UI module to present notifications and actions, you can listen to a series of lifecycle events emitted during the notification presentation process. In more advanced implementations, these events can be leveraged to execute additional logic — such as tracking analytics, updating application state, or triggering custom navigation behaviors.

To do this, you can listen to the following events as needed:

ActitoPushUI.onNotificationWillPresent((notification) => { });

ActitoPushUI.onNotificationPresented((notification) => { });

ActitoPushUI.onNotificationFinishedPresenting((notification) => { });

ActitoPushUI.onNotificationFailedToPresent((notification) => { });

ActitoPushUI.onNotificationUrlClicked(({ notification, url }) => { });

ActitoPushUI.onActionWillExecute(({ notification, action }) => { });

ActitoPushUI.onActionExecuted(({ notification, action }) => { });

ActitoPushUI.onActionNotExecuted(({ notification, action }) => { });

ActitoPushUI.onActionFailedToExecute(({ notification, action, error }) => { });

ActitoPushUI.onCustomActionReceived(({ notification, action, url }) => { });

Notification Presentation Events

These methods notify you of each stage in a notification’s presentation lifecycle:

• onNotificationWillPresent: Called immediately before the notification is displayed.

ActitoPushUI.onNotificationWillPresent((notification) => {
  console.log(`About to present notification: ${notification.id}`);
});

• onNotificationPresented: Called right after the notification is presented.

ActitoPushUI.onNotificationPresented((notification) => {
  console.log(`Presented notification: ${notification.id}`);
});

• onNotificationFinishedPresenting: Called when the notification UI has been dismissed or closed.

ActitoPushUI.onNotificationFinishedPresenting((notification) => {
  console.log(`Notification finished presenting: ${notification.id}`);
});

• onNotificationFailedToPresent: Called if an error occurs during presentation.

ActitoPushUI.onNotificationFailedToPresent((notification) => {
  console.log(`Failed to present notification: ${notification.id}`);
});

• onNotificationUrlClicked: Called when the user taps a URL link inside the notification content.

ActitoPushUI.onNotificationUrlClicked(({ notification, url }) => {
  console.log(`Clicked previously configured URL for HTML or Web Page notifications type: ${url}`);
});

Action Execution Events

These methods notify you of each stage in an action’s execution lifecycle:

• onActionWillExecute: Called just before an action is performed.

ActitoPushUI.onActionWillExecute(({ notification, action }) => {
  console.log(`Preparing to execute action: ${action.label}`);
});

• onActionExecuted: Called when the action has been successfully performed.

ActitoPushUI.onActionExecuted(({ notification, action }) => {
  console.log(`Executed action: ${action.type}`);
});

• onActionNotExecuted: Called if an action is available, but has not been executed by the user.

ActitoPushUI.onActionNotExecuted(({ notification, action }) => {
  console.log(`Action not executed: ${action.label}`);
});

• onActionFailedToExecute: Called when the SDK attempted to execute the action but encountered an error.

ActitoPushUI.onActionFailedToExecute(({ notification, action, error }) => {
  console.log(`Action failed: ${error}`);
});

• onCustomActionReceived: Gives you an opportunity to intercept and decide how to handle a custom action.

ActitoPushUI.onCustomActionReceived(({ notification, action, url }) => {
  console.log(`Received a custom action to execute: ${action.label}`);
});

Notification Options

The Actito SDK allows you to customize how notifications behave in your app by exposing iOS’s native authorization, presentation, and category options through a unified interface.

While the SDK provides default configurations that work for most cases, you may want to fine-tune how your app requests notification permissions, how messages appear while in the foreground, or how notification actions are grouped and displayed. These options can be defined before enabling remote notifications and give you full control over your app’s notification experience.

This guide describes the available customization points:

• Authorization options — Options that determine the authorized features of remote notifications.
• Presentation options — Determine how notifications are displayed when your app is active.
• Category options — Configure how categories and actions behave for interactive or rich notifications.

Authorization options

By default, our library defines UNAuthorizationOptions.alert, UNAuthorizationOptions.badge and UNAuthorizationOptions.sound.

To define authorization options please add the following to your AppDelegate and customise as needed:

const options: ActitoAuthorizationOptions[] = [
  'alert',
  'badge',
  'sound',
  'carPlay',
  'providesAppNotificationSettings',
  'provisional',
  'criticalAlert',
  'announcement',
];

await ActitoPush.setAuthorizationOptions(options);

You can find more information about authorization options in Apple's Documentation.

note

The UNAuthorizationOptions.provisional option will register for notifications with provisional authorization, this means that users will not be prompted to with the permission dialog to accept notifications. Although this might be a great way to opt-in users to remote notifications, any message you sent afterward will be delivered quietly. Messages delivered quietly will not be shown in the lock screen or play a sound.

Also note that if you implement the UNAuthorizationOptions.providesAppNotificationSettings option, notifications from your app will display a button in both the Instant Tuning menu and Notification Settings. The purpose of that button is to provide users a shortcut to your app settings where they can fine-tune which kind of notifications they would like to receive. Implementing such settings views is highly recommended as it could be the reason between allowing your app to keep display notifications or being mute completely. If you do implement this option it is mandatory that you implement the following ActitoPushDelegate method:

ActitoPush.onShouldOpenNotificationSettings((notification) => {
  // Deep link to your settings view.
}),

This will give you the opportunity to present your users with the in-app settings view where you should allow them to customize what kind of notifications they should receive. If the user clicked the button from a specific notification, you will receive that object too. When it comes from the Notification Settings, that object will be nil.

Presentation options

Optionally, you can configure the presentation options to be used when your app is in the foreground. This determines how notifications are displayed while the app is active — for example, showing a banner at the top of the screen, playing a sound, or updating the app badge.

By default, our library sets this as follows:

if #available(iOS 14.0, *) {
    UNNotificationPresentationOptions = [.banner, .sound, .badge]
} else {
    UNNotificationPresentationOptions = [.alert, .sound, .badge]
}

You can adjust these options to best fit your app’s needs by configuring them:

const options: ActitoPresentationOptions[] = [
  'banner',
  'alert',
  'list',
  'badge',
  'sound',
];

await ActitoPush.setPresentationOptions(options);

You can find more information about presentation options in Apple's Documentation.

Category options

If you are using Rich Push Templates you can define category options. These options can define how your notifications and actions will behave. By default, we will use UNNotificationCategoryOptions.customDismissAction and UNNotificationCategoryOptions.hiddenPreviewsShowTitle, but you can change this behaviour to match your needs:

const options: ActitoCategoryOptions[] = [
    'customDismissAction',
    'allowInCarPlay',
    'hiddenPreviewsShowTitle',
    'hiddenPreviewsShowSubtitle',
    'allowAnnouncement',
];

await ActitoPush.setCategoryOptions(options);

You can find more information about category options in Apple's Documentation.