Adding Deep Linking Support

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

1. To enable deep links for your app, make sure to complete the Singular Links Prerequisites.

2. Implement the Singular Links Handler

   The Singular Link Handler provides a callback mechanism to retrieve deep link (_dl), deferred deep link (_ddl), and passthrough (_p) parameters from a Singular tracking link. These parameters are passed when the app is opened (if already installed) or after the app is installed.

   ---

Update the SingularConfig object

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

private void initSingularSDK() {
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET")
            .withSingularLink(getIntent(), new SingularLinkHandler() {
                @Override
                public void onResolved(SingularLinkParams params) {
                    String deeplink = params.getDeeplink();
                    String passthrough = params.getPassthrough();
                    boolean isDeferred = params.isDeferred();
                    Log.d("SingularLink", "Deeplink: " + (deeplink != null ? deeplink : "null"));
                    Log.d("SingularLink", "Passthrough: " + (passthrough != null ? passthrough : "null"));
                    Log.d("SingularLink", "Is Deferred: " + isDeferred);
                }
            });
    try {
        Singular.init(getApplicationContext(), config);
        Log.d("Singular", "SDK initialized successfully");
    } catch (Exception e) {
        Log.e("Singular", "SDK initialization failed: " + e.getMessage());
    }
}

private fun initSingularSDK() {
    val config = SingularConfig("SDK KEY", "SDK SECRET")
        .withSingularLink(intent) { params ->
            val deeplink = params.deeplink
            val passthrough = params.passthrough
            val isDeferred = params.isDeferred

            Log.d("SingularLink", "Deeplink: ${deeplink ?: "null"}")
            Log.d("SingularLink", "Passthrough: ${passthrough ?: "null"}")
            Log.d("SingularLink", "Is Deferred: $isDeferred")
        }

    try {
        Singular.init(applicationContext, config)
        Log.d("Singular", "SDK initialized successfully")
    } catch (e: Exception) {
        Log.e("Singular", "SDK initialization failed: ${e.message}")
    }
}

Notes on SingularLinkHandler 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 SingularLinkHandler 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 SingularLinkHandler'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 SingularLinkHandler.
• 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 SingularLinkHandler.