App Push Destination URL & Tracking Guide

Purpose

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

The app is responsible for displaying notifications and navigating to the destination after a notification is tapped.

Push Notification Payload

By default, OmniSegment sends data-only messages to Android devices.

In FirebaseMessagingService.onMessageReceived, use remoteMessage.getData() to obtain the notification data:

Map<String, String> data = remoteMessage.getData();

The following JSON illustrates the contents of this map. It is a simplified example, not the complete RemoteMessage object.

{
  "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"
}

Fields

Field	Type	Description
title	String	Notification title.
body	String	Notification body.
destination_url	String	Destination configured in the OmniSegment push template.
omnisegment_tracking_url	String	URL generated by OmniSegment for click tracking.
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 in the map.

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

Displaying Notifications

Data-only messages are not automatically displayed as notifications. Your app must create the notification and preserve its custom data for the click handler.

For image notification examples, see the Firebase Push Notification (FCM) Payload Guide.

If your OmniSegment configuration sends notification + data messages instead:

• Standard notification text is available through remoteMessage.getNotification().
• Custom fields remain in remoteMessage.getData().
• When a background notification is tapped, Firebase delivers custom fields through the destination Activity's Intent extras.

SDK Version 1.0.6 and Later

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

Parameters

Parameter	Type	Description
data	Map<String, String>	Custom data associated with the notification.
isUserClicked	Boolean	Set to true when the user taps the notification. Defaults to false when omitted.

OmniSegment.handleNotification(data, true);

Call this method from the notification click handler, not from onMessageReceived.

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: Preserve Data for a Notification Tap

When creating a local notification, attach the data to an Intent targeting your destination Activity directly:

Bundle pushData = new Bundle();
for (Map.Entry<String, String> entry : data.entrySet()) {
    pushData.putString(entry.getKey(), entry.getValue());
}

Intent openIntent = new Intent(this, MainActivity.class);
openIntent.putExtra("omnisegment_push_data", pushData);

PendingIntent pendingIntent = PendingIntent.getActivity(
    this,
    notificationId,
    openIntent,
    PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
);

Use this pendingIntent as the notification builder's content intent:

builder.setContentIntent(pendingIntent);

notificationId should identify the notification being displayed. Use distinct identities for notifications that must retain different click data.

Example: Handle the Notification Tap

Add the following handling to your destination Activity. Integrate it with your existing Activity initialization and UI code.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    handlePushIntent(getIntent());
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    setIntent(intent);
    handlePushIntent(intent);
}

private void handlePushIntent(Intent intent) {
    if (intent == null) {
        return;
    }

    Bundle pushData = intent.getBundleExtra("omnisegment_push_data");
    if (pushData == null) {
        return;
    }

    intent.removeExtra("omnisegment_push_data");

    Map<String, String> data = new HashMap<>();
    for (String key : pushData.keySet()) {
        String value = pushData.getString(key);
        if (value != null) {
            data.put(key, value);
        }
    }

    String trackingUrl = data.get("omnisegment_tracking_url");
    if (trackingUrl != null && !trackingUrl.isEmpty()) {
        OmniSegment.handleNotification(data, true);
    }
}

This example handles the custom Bundle created by the local notification example above. For notifications displayed automatically by Firebase, read the custom fields from the Activity's Intent extras instead.

Integration Notes

• Initialize OmniSegment before processing notification clicks.
• Handle clicks in both onCreate and onNewIntent.
• Ensure each notification click is processed once, including Activity recreation or app relaunch.
• 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 to the destination.

SDK Versions Earlier Than 1.0.6

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