Supporting Push Notifications

Track user interactions with push notifications to measure re-engagement campaigns and attribute conversions accurately by integrating Firebase Cloud Messaging (FCM) with the Singular SDK.

Follow the implementation guidelines below to ensure notification data is correctly passed to the Singular SDK for proper attribution.

Implementation Guide

Integrate the Singular SDK

Integrate the Singular SDK in your Unity project using the standard installation instructions as documented in the Singular Unity SDK guide.

Configure Push Link Paths

Define the JSON paths where Singular tracking links are located within your push notification payload structure.

Configure push link paths using forward-slash delimited strings that specify the key path to the Singular link in your notification data structure.

// Configure push link paths in SDK initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithPushNotificationsLinkPaths(new List<string> 
    {
        "sng_link",                                    // Top-level key
        "path/to/url",                                 // Nested path
        "rootObj/nestedObj/singularLink"               // Deep nested path
    });

SingularSDK.InitializeSingularSDK();

Path Configuration Examples:

• Simple Keys: Use "sng_link" for top-level keys in the payload
• Nested Keys: Use "rootObj/nestedObj/key" to traverse nested JSON structures
• Multiple Paths: Define multiple path strings to check different possible locations for Singular links

Platform-Specific Handling

iOS Push Notification Handling

Terminated State (App Not Running)

No manual action is required for iOS apps in terminated state. The Singular iOS integration automatically handles push tracking using SingularAppController.

Background State (App Running in Background)

When a notification is received while the app is in the background, use HandlePushNotification() to pass push data to the SDK.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class PushNotificationHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase message received event
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received Firebase push notification");

        // Extract notification data
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Pass notification data to Singular SDK
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your additional notification handling logic
        DisplayNotification(e.Message);
    }
}

Android Push Notification Handling

Automatic Handling (Recommended)

Ensure your main Unity activity extends SingularUnityActivity for automatic push notification handling in both background and terminated states.

import com.singular.unitybridge.SingularUnityActivity;

public class MessagingUnityPlayerActivity extends SingularUnityActivity {
    // Your custom activity logic here

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Your initialization code
    }
}

Firebase Integration Example

If you need custom Firebase message handling logic, implement a listener and forward notification data to Singular.

using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;

public class AndroidPushHandler : MonoBehaviour
{
    void Start()
    {
        // Subscribe to Firebase messaging events
        Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
        Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
    }

    private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
    {
        Debug.Log("Received a new Firebase message");

        // Convert message data to dictionary
        var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);

        // Forward to Singular SDK for attribution
        SingularSDK.HandlePushNotification(pushDataDictionary);

        // Your custom handling logic
        ProcessNotificationContent(e.Message);
    }

    private void OnTokenReceived(object sender, TokenReceivedEventArgs token)
    {
        Debug.Log($"FCM Token received: {token.Token}");

        // Store or use token as needed
        // Note: Singular automatically handles token registration
    }

    private void ProcessNotificationContent(FirebaseMessage message)
    {
        // Your custom notification display or routing logic
        string title = message.Notification?.Title ?? "Notification";
        string body = message.Notification?.Body ?? "";

        Debug.Log($"Notification: {title} - {body}");
    }
}

Validation Guide

Verify Payload in Start Session

Confirm that push notification links are correctly passed to Singular by inspecting the start session API call.

The Singular SDK includes the push notification payload under the singular_link parameter in the start session request when users tap notifications.

Example Start Session Request:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=com.yourcompany.app
&s=1740905574084
&sdk=Singular/Unity-v1.0.0

Advanced Configuration

ESP Domain Configuration

Configure external domains if you wrap Singular links within Email Service Provider (ESP) or other third-party domains.

// Configure ESP domains for wrapped Singular links
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .WithESPDomains(new List<string> { "sl.esp.link", "custom.domain.com" });

SingularSDK.InitializeSingularSDK();

Dynamic Deep Link Routing

Implement multiple deep link destinations from a single notification by configuring one Singular tracking link with dynamic redirect overrides.

Use Case Example: A breaking news notification with multiple action options

• Read Latest News:newsapp://article?id=12345
• Trending Topics: newsapp://trending
• Sports: newsapp://sports

Instead of creating multiple tracking links, use one Singular link and override redirects dynamically based on user selection. See Overriding Redirects in Singular Tracking Links for implementation details.

Important Considerations

Implementation Notes

• No Callback Handler: Unlike SetSingularLinkHandler, the push notification feature does not provide payload callbacks. Implement your own deep linking logic to route users to specific content within your app
• Attribution Flow: When users tap notifications, Singular retrieves the payload and includes it in the start session event triggered by SDK initialization. The backend processes this data to attribute the push notification touchpoint and register re-engagement tracking
• Domain Restrictions: Only Singular link domains (sng.link) from the Manage Links page are permitted by default. Configure ESP domains explicitly for wrapped links using WithESPDomains()
• Platform Differences: iOS automatically handles terminated state notifications, while Android requires extending SingularUnityActivity for automatic handling