Android SDK: Implementing Deep Links

Singular Android SDK
Download
Singular Android SDK version 9.4.1
Compatibility

Android 4.0.1 (Ice Cream Sandwich) and higher

  • The SDK uses the device's Android Advertising ID for devices that use Play Store version 4. For older devices, the SDK uses the Android ID.
  • The latest version of the SDK has not been tested with Android versions older than 4.0.1.
Sample App Review our sample app for an example of a complete SDK integration based on best practices.
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep Links
  4. Advanced Options

 

Introduction

Deep links are links that lead into specific content inside an app. When a user clicks a deep link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep linking as well as deferred deep linking (see our Deep Linking FAQ and the Singular Links FAQ for more information).

The instructions below will show you how to:

  1. Access the tracking link that led to your app being opened,
  2. Read the deep link destination, and
  3. Show the appropriate content.

Note: This article assumes your organization is using Singular Links - Singular's new tracking link technology, launched in 2019.

Older customers of Singular may be using Singular's older tracking links (legacy links). To support deep linking with legacy links, see Handling Deep Links with Legacy Links.

Enabling Deep Links

To enable deep links for your app, see Singular Links Prerequisites.

Adding a Deep Linking Intent Filter

To enable deep link support in an activity, add an intent filter like the following to your AndroidManifest.xml. If you have more than one activity that should be opened through a deep link, do this for each of the activities.

<activity> 
    <intent-filter>
        <data android:scheme="singular-example" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

Handling Deep Links

The Singular SDK provides a handler mechanism to read the details of the tracking link that led to the app being opened.

To use the handler, add the following code in the activity's onCreate method. Again, do this for every activity that should be opened through a deep link.

  1. Call withSingularLink when you create the SingularConfig object.
  2. Inside the SingularLinksHandler, override the onResolved method to read the deep link and process it.
protected void onCreate(Bundle savedInstanceState) {
    SingularConfig config = new SingularConfig(apiKey, secretKey);
    config.withSingularLink(getIntent(), new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // The deep link destination, as configured in the Manage Links page
            String deeplink = params.getDeeplink();
            
            // The passthrough parameters added to the link, if any.
            String passthrough = params.getPassthrough();
            
            // Whether the link configured as a deferred deep link.
            boolean isDeferred = params.isDeferred();
            
            // Add deep link handling code here
        }
    });
    Singular.init(context, config);
}

Note: The SingularLinkHandler is called only if the app was opened through a Singular Link (see the Singular Links FAQ). Other types of deep links will not trigger the handler.

Modifying the Deferred Deep Link Timeout

By default, when an app sends the first session to Singular from a certain device, the Singular server looks in its records to see if there is a deferred deep link that matches that device (see What are deferred deep links?). If a deferred deep link is found, it is sent back to the app to process. But if no deferred deep link is found within 60 seconds, the server stops searching.

You can modify the timeout value by calling withDDLTimeoutInSec when you create the SingularConfig object. The example below changes the timeout to 30 seconds:

SingularConfig config = new SingularConfig(apiKey, secretKey);
config.withSingularLink(getIntent(), new SingularLinkHandler() {
    ...
});
config.withDDLTimeoutInSec(30);

If you are an older Singular customer, you may be using legacy tracking links (Singular's older tracking link mechanism) rather than the newer Singular Links. Legacy links are managed in the Create Link and View Links pages, and they also provide deep linking and deferred deep linking functionality.

To handle deep linking with legacy links, call the withDDLHandler method when you create your SingularConfig object, like in the example below. Inside the DeferredDeepLinkHandler, override the handleLink method and process the link string.

Note: Whether you use Singular Links or legacy links, you can still set the deferred deep link timeout withDDLTimeoutInSec.

SingularConfig config = new SingularConfig(apiKey, secretKey);
config.withDDLHandler(new DeferredDeepLinkHandler() {
    @Override
    public void handleLink(String link) {
        // Deep link handling code
        // Note: handleLink() is invoked in the UI (main) thread
    }
});
Was this article helpful?