App Push Destination URL & Tracking Guide

Purpose

This guide explains how to read OmniSegment push notification data and track notification clicks in your React Native app.

The examples use the RemoteMessage interface from @react-native-firebase/messaging. Notification display and navigation are handled by your app and its notification library.

Push Notification Payload

OmniSegment's React Native handleNotification method reads custom fields from remoteMessage.data.

The following examples show simplified callback objects. Firebase may include additional metadata.

Android

With OmniSegment's default Android data-only configuration, notification text and custom fields are all inside data.

{
  "data": {
    "title": "Example notification",
    "body": "View the example product",
    "destination_url": "https://shop.example/products/123",
    "omnisegment_tracking_url": "https://tracking.example/collect?goto=1",
    "image_url": "https://cdn.example/notification.jpg"
  }
}

Data-only messages are not automatically displayed as notifications. Your app must display a local notification and handle its press event using its chosen notification library.

iOS

For a standard visible iOS notification, notification text is available under notification, while custom fields are inside data.

{
  "notification": {
    "title": "Example notification",
    "body": "View the example product"
  },
  "data": {
    "destination_url": "https://shop.example/products/123",
    "omnisegment_tracking_url": "https://tracking.example/collect?goto=1",
    "image_url": "https://cdn.example/notification.jpg"
  }
}

Custom Fields

Field	Type	Description
data.destination_url	String	Destination configured in the OmniSegment push template.
data.omnisegment_tracking_url	String	URL generated by OmniSegment for click tracking.
data.image_url	String	Optional image URL configured in the template.

destination_url and image_url may be absent when they are not configured. Additional OmniSegment metadata and template-defined fields may also appear inside data.

The URLs above are illustrative. For click tracking, use the complete omnisegment_tracking_url received in the notification.

Image Notifications

Displaying an image requires platform-specific handling:

• Android data-only messages require image handling in the local notification implementation.
• iOS image notifications require a native Notification Service Extension.

The custom image_url field does not automatically display an image.

SDK Version 1.1.5 and Later

Use OmniSegment.handleNotification(remoteMessage, true) to track a notification click.

Parameters

Parameter	Type	Description
remoteMessage	Object containing data	Notification object whose data contains the OmniSegment custom fields.
isUserClicked	Boolean	Set to true when the user taps the notification. Defaults to false.

OmniSegment.handleNotification(remoteMessage, true);

Pass the notification object containing data, rather than passing remoteMessage.data directly.

The method tracks the click and sends an event using the resolved destination as its location. Navigation must be handled separately by your app.

Example: Handle Remote Notification Opens

The following example uses the namespaced React Native Firebase API. If your installed version requires the modular API, use its equivalent methods.

Register these handlers once after initializing OmniSegment:

import messaging, {
  FirebaseMessagingTypes,
} from '@react-native-firebase/messaging';
import OmniSegment from '@bebit-tech/omnisegment';

function handleNotificationOpen(
  remoteMessage: FirebaseMessagingTypes.RemoteMessage
): void {
  const trackingURL = remoteMessage.data?.omnisegment_tracking_url;

  if (typeof trackingURL !== 'string' || trackingURL.length === 0) {
    return;
  }

  OmniSegment.handleNotification(remoteMessage, true);
}

const unsubscribe = messaging().onNotificationOpenedApp(
  handleNotificationOpen
);

void messaging().getInitialNotification().then((remoteMessage) => {
  if (remoteMessage) {
    handleNotificationOpen(remoteMessage);
  }
});

onNotificationOpenedApp handles notification opens while the app is in the background. getInitialNotification checks whether a notification opened the app from a terminated state.

Call unsubscribe() when disposing of the listener.

These handlers apply when React Native Firebase owns the notification-open events. Other libraries, such as Notifee, may own those events instead.

Locally Displayed Notifications

For a locally displayed notification, use your notification library's press handler.

Preserve the original custom data when displaying the notification. When the user taps it, provide the custom fields under data:

OmniSegment.handleNotification(
  { data: customData },
  true
);

Here, customData is the custom data retrieved from the local notification's press event. Its exact location depends on the notification library.

Integration Notes

• Initialize OmniSegment before processing notification clicks.
• onMessage and setBackgroundMessageHandler are receipt handlers, not click handlers.
• Preserve custom data when creating local notifications.
• Ensure each click is processed once across initial-notification, open, and local-press handlers.
• Calling the SDK click handler and manually requesting the tracking URL for the same click can duplicate tracking.
• destination_url does not trigger automatic navigation. Your app controls routing and should wait until its navigation system is ready.

SDK Versions Earlier Than 1.1.5

For manual tracking and destination resolution, see the App Push Destination URL & Tracking Guide.