Android SDK: Implementing Deep Links

Singular Android SDK
Download
Singular Android SDK version 12.0.9 (see Change Log)
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.

Note: To get your Singular SDK Key and SDK Secret, log into your Singular account and go to Developer Tools > SDK Keys.

protected void onCreate(Bundle savedInstanceState) {
    SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");
    List<String> supportedDomains = Arrays.asList("subdomain.mywebsite.com", "subdomain2.mywebsite.com"); 
        
    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
            }
        }, 
        supportedDomains
    );
    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 app links will only trigger if the domain is included in supportedDomains when you create the Singular Config object. See "Handling Non-Singular Deep Links" for more information

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("SDK KEY", "SDK SECRET");
config.withSingularLink(getIntent(), new SingularLinkHandler() {
    ...
});
config.withDDLTimeoutInSec(30);

Handling Non-Singular Deep Links

The Singular SDK provides support for handling non-Singular-served deep links. This is required for measuring attribution for partners who support deep links, such as Google Ads.

To support these deep links, provide a list of supported Android app links in supportedDomains when you create your SingularConfig object:

SingularConfig config = new SingularConfig("SDK KEY", "SDK SECRET");

// supportedDomains
List<String> supportedDomains = Arrays.asList("subdomain.mywebsite.com", "subdomain.myotherwebsite.com");
config.withSingularLink(
    getIntent(), 
    new SingularLinkHandler() {
        @Override
        public void onResolved(SingularLinkParams params) {
            // handle callback
        }
    }, 
    supportedDomains
);