Supporting Deep Links

Deep links are URLs that direct users to specific content within an app. When a user taps a deep link on a device where the app is already installed, the app opens directly to the intended product page or experience. Singular tracking links support both deep linking and deferred deep linking. For more details, see our Deep Linking FAQ and Singular Links FAQ.

Requirements

• Complete the Singular Links Prerequisites.

Implementation

Update the iOS AppDelegate

iOS Prerequisites

To enable the Singular SDK to process launch-related data and handle deep links in your iOS app, you need to pass the launchOptions and userActivity objects to the Singular SDK in your AppDelegate.m file. These objects, provided by iOS, contain critical information about how and why your app was launched, which Singular uses for attribution tracking and deep link navigation.

// Top of AppDelegate.m
#import "SingularAppDelegate.h"

- (BOOL)application:(UIApplication *)application 
     didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       [GeneratedPluginRegistrant registerWithRegistry:self];
       [SingularAppDelegate shared].launchOptions = launchOptions;
       return [super application:application 
         didFinishLaunchingWithOptions:launchOptions];
}

- (BOOL)application:(UIApplication *)application 
     continueUserActivity:(NSUserActivity *)userActivity 
     restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> 
       *restorableObjects))restorationHandler {
         [[SingularAppDelegate shared] continueUserActivity:userActivity 
           restorationHandler:restorationHandler];
     return [super application:application continueUserActivity:userActivity 
         restorationHandler:restorationHandler ];
}

- (BOOL)application:(UIApplication *)app 
     openURL:(NSURL *)url 
     options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
       [[SingularAppDelegate shared] handleOpenUrl:url options:options];
       return [super application:app openURL:url options: options];
}

import singular_flutter_sdk
  
override func application(_ application: UIApplication, 
  didFinishLaunchingWithOptions
  launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    GeneratedPluginRegistrant.register(with: self) if 
      let singularAppDelegate = SingularAppDelegate.shared() {
        singularAppDelegate.launchOptions = launchOptions
      }
  return super.application(application, didFinishLaunchingWithOptions:launchOptions)
}

override func application(_ application: UIApplication, 
  continue userActivity:NSUserActivity, 
  restorationHandler: @escaping ([UIUserActivityRestoring]?)-> Void) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.continueUserActivity(userActivity, restorationHandler:nil)
    }
  return super.application(application, continue:userActivity, 
    restorationHandler: restorationHandler);
}

override func application(_ app: UIApplication, 
  open url: URL, options:[UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.handleOpen(url, options: options)
    }
  return super.application(app, open: url, options: options);
}

Update the Android MainActivity

Android Prerequisites

To enable the Singular SDK to process launch-related data and handle deep links in your Android app, you need to modify the MainActivity file to pass the Intent object to the Singular SDK. The Intent object, provided by the Android system, contains information about how and why your app was launched, which Singular uses for attribution tracking and deep link navigation.

// Add as part of the imports at the top of the class
import android.content.Intent;
import com.singular.flutter_sdk.SingularBridge;

// Add to the MainActivity class
@Override
public void onNewIntent(Intent intent) {
  if(intent.getData() != null) {
    setIntent(intent);
    super.onNewIntent(intent);
    SingularBridge.onNewIntent(intent);
  }
}

// Add as part of the imports at the top of the class
import android.content.Intent
import com.singular.flutter_sdk.SingularBridge

// Add to the MainActivity class
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    if (intent.data != null) {
        setIntent(intent)
        SingularBridge.onNewIntent(intent)
    }
}

Update the SingularConfig object

• Add the singularLinksHandler callback to the SingularConfig object during the SDK initialization to handle incoming deep link and deferred deep link data.

Notes on singularLinksHandler callback Behavior:

• On a fresh install, there is no Open URL when the app is launched. Therefore, Singular must complete attribution to the last touchpoint and determine if the tracking link contained a configured Deep Link or Deferred Deep Link (DDL) value. This process occurs when the Singular SDK sends the first session to the Singular servers. If applicable, the deep link value is returned to the SDK's singularLinksHandler callback and presented in the "deeplink" parameter.

  To test this scenario:

  1. Uninstall the app from the device (if currently installed).
  2. Reset your Google Advertising ID (GAID).
  3. Click the Singular tracking link from the device. Be sure the Singular tracking link is configured with a deep link value.
  4. Install and open the app.

  Pro Tip: When testing deep links or deferred deep links in a development version of your app with a different package name (e.g., com.example.dev instead of com.example.prod), ensure the tracking link is configured specifically for the development app’s package name, not the production app’s. Additionally, after clicking the test link on your device, install the development build directly onto the test device (e.g., via Android Studio or an APK) rather than downloading the production app from the app store.

  Attribution should complete successfully, and the DDL value will be passed to the app.

• If a passthrough (_p) parameter is included in the tracking link, the singularLinksHandler callback's passthrough parameter will contain the corresponding data. This is useful for capturing additional data from the click in the app.
• To capture all query parameters from the tracking link URL, append the _forward_params=2 parameter to the tracking link. All query parameters will be included in the deeplink parameter of the singularLinksHandler callback.
• If the app is already installed, clicking a Singular Link will open the app. Singular uses the Android App Links technology to accomplish this. The Android OS will provide an Open URL containing the entire Singular tracking link. During SDK initialization, the Singular SDK will parse the Android Intent, extract the deeplink and passthrough values, and return them through the singularLinksHandler callback.