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 Cordova project using the standard installation instructions as documented in the Singular Cordova SDK guide.

Set Up Firebase Cloud Messaging

Configure push notifications in your Cordova project using a plugin like @havesource/cordova-plugin-push and follow Firebase's setup guide for platform-specific integration.

iOS Configuration

Register your iOS app in Firebase and configure push notification capabilities in Xcode.

1. Register iOS App: Create an iOS app in your Firebase Console project
2. Add Configuration File: Download GoogleService-Info.plist and include it in your iOS platform folder
3. Enable Capabilities: In Xcode project settings, enable Push Notifications capability
4. Enable Background Modes: Enable Background Modes and check Remote notifications

Android Configuration

Register your Android app in Firebase and add the configuration file to your project.

1. Register Android App: Create an Android app in your Firebase Console project
2. Add Configuration File: Download google-services.json and place it in platforms/android/app/
3. Verify Dependencies: Ensure the Firebase plugin is properly installed and messaging permissions are granted

Configure Push Link Paths

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

Configure push link paths by passing arrays of strings that specify the key path to the Singular link in your notification data structure. Each path is an array representing the nested structure of keys.

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

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 arrays to check different possible locations for Singular links

For complete method documentation, see withPushNotificationsLinkPaths reference.

Platform-Specific Handling

Configure platform-specific code to pass notification data to the Singular SDK based on the app state when users interact with push notifications.

iOS Push Notification Handling

App in Terminated State

Configure your iOS AppDelegate to pass launch options to the Singular SDK for automatic push tracking when the app opens from a terminated state.

In your native iOS code within AppDelegate.m, call the following method inside didFinishLaunchingWithOptions:

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

App in Background or Foreground

Use the handlePushNotification() method to pass push data to the SDK when the app receives notifications in background or foreground states.

Call the following method in your JavaScript code where the push notification is handled:

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

For complete method documentation, see handlePushNotification reference.

Android Push Notification Handling

App in Terminated State

No action is required for Android apps in terminated state. The Cordova bridge layer handles this scenario automatically when users tap notifications.

App in Background or Foreground

Configure your Android MainActivity to pass notification intents to the Singular SDK when the app is in background or foreground states.

In your main Cordova activity (e.g., MainActivity.java), override onNewIntent:

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

Additionally, implement push message handling in your JavaScript code using the same approach shown for iOS background/foreground handling above.

Validation Guide

Verify that push notification tracking is working correctly by inspecting the Singular SDK's start session calls and monitoring attribution data.

Verify Payload in Start Session

Check API Call Parameters

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=net.singular.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

Advanced Configuration

Implement advanced push notification features including ESP domain configuration and dynamic deep link routing for complex notification scenarios.

ESP Domain Configuration

Configure External Domains

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

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure ESP domains for wrapped Singular links
config.withESPDomains(['sl.esp.link', 'custom.domain.com']);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

For complete method documentation, see withESPDomains reference.

Dynamic Deep Link Routing

Multiple Actions from Single Notification

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.

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

Important Considerations

Understand key implementation details and limitations when integrating push notification tracking with the Singular SDK.

Implementation Notes

Key Behaviors and Limitations

• No Callback Handler: Unlike withSingularLink, the push notification feature does not provide payload callbacks. You must implement your own deep linking logic to route users to specific content within your app based on the notification data
• Attribution Flow: When users tap notifications, Singular retrieves the payload and includes it in the start session event triggered by Singular.init(config). 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 requires AppDelegate configuration for terminated state handling, while Android handles it automatically through the bridge module for terminated state scenarios
• Path Configuration: The SDK searches for Singular links using the paths defined in withPushNotificationsLinkPaths(). Ensure your notification payload structure matches the configured paths for proper link extraction

Testing Recommendations

1. Test All App States: Verify push tracking works correctly when app is terminated, backgrounded, and in foreground
2. Validate Payload Structure: Confirm your notification payload includes Singular links at the configured paths
3. Check Start Session Calls: Use network monitoring tools to verify the singular_link parameter appears in start session requests
4. Monitor Attribution: Check the Singular SDK Console to confirm push notifications are correctly attributed in your campaign data
5. Test Deep Linking: Verify users are correctly navigated to intended content when tapping different notification types