Supporting Push Notifications

Track user interactions with push notifications to measure re-engagement campaigns and attribute conversions accurately by integrating Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs) 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 Unreal Engine project using the standard installation instructions as documented in the Singular Unreal Engine SDK guide.

Register Push Token

Register your push notification token with Singular to enable uninstall tracking and push attribution.

// Register push token for uninstall tracking
void UYourGameInstance::OnPushTokenReceived(const FString& Token)
{
    // Pass the FCM or APNs token to Singular
    USingularSDKBPLibrary::SetUninstallToken(Token);
    UE_LOG(LogTemp, Log, TEXT("Push token registered: %s"), *Token);
}

Method Signature:

static void SetUninstallToken(FString token);

Platform-Specific Handling

iOS Push Notification Handling

Configure Push Notification Paths

For iOS implementations, configure the JSON paths where Singular tracking links are located within your push notification payload structure during SDK initialization.

// iOS: Configure push notification link paths in initialization
// Note: This is typically configured through the iOS native bridge
// The Singular iOS SDK automatically handles push tracking when configured

// Example configuration in iOS native code (Objective-C):
// SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" andSecret:@"API_SECRET"];
// config.singularLinksHandler = ^(SingularLinkParams * _Nonnull params) {
//     // Handle deep link from push notification
// };
// [Singular start:config];

Terminated State (App Not Running)

No manual action is required for iOS apps in terminated state. The Singular iOS integration automatically handles push tracking when users tap notifications while your app is not running.

Background State (App Running in Background)

When a notification is received while the app is in the background, the iOS SDK automatically processes the notification data. No additional C++ code is required beyond the initial token registration.

Android Push Notification Handling

Firebase Cloud Messaging Integration

For Android implementations, integrate Firebase Cloud Messaging (FCM) and forward push tokens to the Singular SDK for tracking.

// Android: Register FCM token with Singular
void UYourGameInstance::OnFirebaseTokenReceived(const FString& FcmToken)
{
    // Register the FCM token for uninstall tracking
    USingularSDKBPLibrary::SetUninstallToken(FcmToken);
    UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FcmToken);
}

Handling Push Notification Data

When users tap push notifications containing Singular tracking links, ensure the notification data is passed to your app's deep link handler for proper attribution.

// Handle notification tap event
void UYourGameInstance::OnNotificationTapped(const FString& NotificationData)
{
    // Parse notification data for Singular links
    // Example: Extract "sng_link" or custom key from notification payload

    // If notification contains a Singular tracking link, it will be
    // automatically processed by the SDK's deep link handler

    UE_LOG(LogTemp, Log, TEXT("Notification tapped: %s"), *NotificationData);

    // Route user to appropriate content
    ProcessNotificationDeepLink(NotificationData);
}

void UYourGameInstance::ProcessNotificationDeepLink(const FString& LinkData)
{
    // Your custom deep link routing logic
    if (LinkData.Contains(TEXT("article")))
    {
        // Navigate to article
        OpenArticleScreen();
    }
    else if (LinkData.Contains(TEXT("promotion")))
    {
        // Navigate to promotion
        OpenPromotionScreen();
    }
}

Validation Guide

Verify Push Token Registration

Confirm that push notification tokens are correctly registered with Singular by checking SDK logs during app initialization.

// Enable SDK logging to verify token registration
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging for debugging
    5,                       // Verbose log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

// After receiving push token
FString PushToken = GetPushNotificationToken();
USingularSDKBPLibrary::SetUninstallToken(PushToken);

// Check logs for confirmation:
// "Push token registered successfully" or similar message

Verify Attribution in Dashboard

Use the Singular dashboard to verify that push notification interactions are being tracked correctly.

• Re-engagement Campaigns: Check the Re-engagement section in your dashboard to see push notification campaign performance.
• User-Level Data: Export user-level data to verify that push notification touchpoints are being recorded with the correct attribution.
• Conversion Events: Confirm that events triggered after push notification taps are attributed to the correct campaign.

Advanced Configuration

Custom Notification Payload Structure

Structure your push notification payloads to include Singular tracking parameters alongside your custom data.

Recommended Payload Structure (JSON):

{
  "notification": {
    "title": "Special Offer!",
    "body": "Get 50% off today only"
  },
  "data": {
    "sng_link": "https://yourapp.sng.link/Abc12?_dl=myapp://promo",
    "campaign_id": "summer_sale_2025",
    "promo_code": "SAVE50",
    "deep_link": "myapp://promo/summer"
  }
}

Key Elements:

• sng_link: The Singular tracking link for attribution (required for push tracking).
• campaign_id: Your internal campaign identifier for reference.
• deep_link: Your app's custom deep link for content routing.
• Custom data: Any additional data needed by your app (promo codes, user segments, etc.).

Deep Link Routing Implementation

Implement a centralized deep link handler to route users to specific content when they tap push notifications.

// Centralized deep link handler
class UDeepLinkHandler : public UObject
{
public:
    void HandleDeepLink(const FString& DeepLink)
    {
        // Parse the deep link URL
        if (DeepLink.StartsWith(TEXT("myapp://article/")))
        {
            FString ArticleId = ExtractArticleId(DeepLink);
            NavigateToArticle(ArticleId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://promo/")))
        {
            FString PromoId = ExtractPromoId(DeepLink);
            NavigateToPromotion(PromoId);
        }
        else if (DeepLink.StartsWith(TEXT("myapp://profile")))
        {
            NavigateToUserProfile();
        }
        else
        {
            // Default: Navigate to home screen
            NavigateToHome();
        }
    }

private:
    FString ExtractArticleId(const FString& Url)
    {
        // Extract article ID from URL
        FString ArticleId;
        Url.Split(TEXT("article/"), nullptr, &ArticleId);
        return ArticleId;
    }

    FString ExtractPromoId(const FString& Url)
    {
        // Extract promo ID from URL
        FString PromoId;
        Url.Split(TEXT("promo/"), nullptr, &PromoId);
        return PromoId;
    }

    void NavigateToArticle(const FString& ArticleId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to article: %s"), *ArticleId);
        // Your navigation logic
    }

    void NavigateToPromotion(const FString& PromoId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to promotion: %s"), *PromoId);
        // Your navigation logic
    }

    void NavigateToUserProfile()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
        // Your navigation logic
    }

    void NavigateToHome()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
        // Your navigation logic
    }
};

Important Considerations

Implementation Notes

• Token Registration Timing: Register the push token with Singular as soon as it's available from FCM or APNs, ideally during or immediately after SDK initialization.
• Attribution Flow: When users tap notifications containing Singular links, the SDK automatically processes the attribution data during the session start event. No manual handling is required for attribution tracking.
• Deep Link Handling: While Singular handles attribution automatically, you must implement custom deep link routing logic to navigate users to the correct in-app content.
• Payload Consistency: Use consistent key names (e.g., "sng_link") across all push notification campaigns to ensure reliable tracking.
• Platform Differences: iOS and Android handle push notifications differently at the system level. Ensure your implementation accounts for platform-specific behavior.
• Uninstall Tracking: The push token is also used for uninstall tracking. Singular sends silent push notifications to detect uninstalled apps, providing valuable retention insights.

Privacy and Permissions

Ensure compliance with platform requirements and user privacy regulations when implementing push notifications.

• iOS Permissions: Users must grant permission to receive push notifications. Request permission at an appropriate time in your app flow, not immediately on first launch.
• Android Permissions: Starting with Android 13 (API level 33), apps must request the POST_NOTIFICATIONS permission to send notifications.
• User Consent: Respect user preferences for receiving marketing communications. Provide clear opt-out mechanisms in your app settings.
• Data Privacy: Avoid including personally identifiable information (PII) in push notification payloads. Use user IDs or other non-PII identifiers.