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.

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("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);
}

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 supports non-Singular-served deep links. This is required for measuring attribution for partners who support deep links, such as Google Ads.

Starting with Android SDK version 12.1.1, non-Singular Universal Links are supported by default.

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
);