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 the AppDelegate.m
#import <Singular-React-Native/SingularBridge.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Add inside didFinishLaunchingWithOptions
    [SingularBridge startSessionWithLaunchOptions:launchOptions];
  return YES;
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
    restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    [SingularBridge startSessionWithUserActivity:userActivity];
    return YES;
}

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 net.singular.react_native.SingularBridgeModule;

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

// Add as part of the imports at the top of the class
import android.content.Intent
import net.singular.react_native.SingularBridgeModule

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

Update the SingularConfig object

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

Notes on withSingularLink 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 withSingularLink 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 withSingularLink 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 withSingularLink 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 withSingularLink callback.