Adding Deep Linking Support

Deep links direct users to specific content within your app. When users tap a deep link on a device with your app installed, the app opens directly to the intended content, such as a product page or specific experience.

Singular tracking links support both standard deep linking (for installed apps) and deferred deep linking (for new installs). For comprehensive information, see the Deep Linking FAQ and Singular Links FAQ.

Requirements

Prerequisites

Complete the Singular Links Prerequisites to enable deep linking for your app.

Implement Singular Links Handler

The SingularLinkHandler provides a callback mechanism to retrieve deep link, deferred deep link, and passthrough parameters from Singular tracking links when the app opens.

Available Parameters:

• Deep Link (_dl): The destination URL within your app for users clicking the link
• Deferred Deep Link (_ddl): The destination URL for users who install the app after clicking the link
• Passthrough (_p): Custom data passed through the tracking link for additional context

Platform Configuration

Android Setup

Configure your Android app to support deep linking through Android App Links technology.

Step 1: Configure Activity

Open Project > Assets > Plugins > Android > AndroidManifest.xml and update the activity name.

Change from:

<activity android:name="com.unity3d.player.UnityPlayerActivity"

Change to:

<activity android:name="com.singular.unitybridge.SingularUnityActivity"

import com.singular.unitybridge.SingularUnityBridge;

@Override
protected void onNewIntent(Intent intent) {
    setIntent(intent);

    // Call this method from your custom activity in onNewIntent
    SingularUnityBridge.onNewIntent(intent);
}

Step 2: Add Intent Filter

Add an Intent Filter to support Android App Links. The android:host value must match your Singular Links domain.

<!-- Added Intent Filter for Singular Android Links Deeplinking -->
<!-- Replace example.sng.link with your Singular Links domain -->
<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="http" />
  <data android:scheme="https" />
  <data android:host="example.sng.link" />
  <data android:pathPrefix="/A"/>
  <data android:pathPrefix="/B"/>
  <data android:pathPrefix="/E"/>
  <data android:pathPrefix="/F"/>
</intent-filter>

Complete the Singular Links Android Prerequisites for detailed setup instructions.

iOS Setup

Configure your iOS app to support deep linking through Universal Links and custom URL schemes.

Step 1: Enable Universal Links

1. Configure Singular Links domain: Set up at least one sub-domain in the Attribution > Manage Links page in Singular
2. Enable Associated Domains: In the Apple Developer Portal, go to Identifiers, select your app, and enable Associated Domains in the Capabilities menu
3. Add domains to Xcode: In your Xcode project, navigate to Project settings > Capabilities > Associated Domains and add your Singular Links domains in the format applinks:yourdomain.sng.link
4. Configure Team ID: Copy your "App Prefix" (Team ID) from the Apple Developer Portal
5. Add Team ID to Singular: In Singular, go to Apps Configuration, find your app, expand the iOS App Advanced Settings, and paste the Team ID. This allows Singular to host the apple-app-site-association file for Universal Links

Step 2: Configure URL Scheme (Fallback)

Add a custom URL scheme as a fallback when Universal Links cannot function.

1. In Singular's iOS App Advanced Settings (below Team ID), enter your iOS App Scheme
2. Register the app scheme as a "URL Type" in your Xcode project under Info > URL Types

SDK Configuration

Add SingularLinkHandler to Your App

Configure the SingularLinkHandler to process incoming deep link and deferred deep link data when your app launches.

Implementation Steps

1. Add the SingularLinkHandler interface to your main class or create a dedicated class and attach it to the SingularSDKObject
2. Add the Singular directive at the top of your script: using Singular;
3. Implement the SingularLinkHandler interface on your class
4. Call SetSingularLinkHandler() to register the handler (recommended in the Awake() function)
5. Override OnSingularLinkResolved() to process the deep link parameters

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Singular;

public class DeepLinkManager : MonoBehaviour, SingularLinkHandler
{
    void Awake()
    {
        Debug.Log("Registering Singular Link Handler");

        // Register this class as the Singular Link handler
        // This will fetch the tracking link details and call OnSingularLinkResolved
        SingularSDK.SetSingularLinkHandler(this);
    }

    // Callback method that receives deep link parameters
    public void OnSingularLinkResolved(SingularLinkParams linkParams)
    {
        Debug.Log("Singular Link Resolved");

        // Extract parameters from the tracking link
        string deeplink = linkParams.Deeplink;
        string passthrough = linkParams.Passthrough;
        bool isDeferred = linkParams.IsDeferred;

        // Log the parameters
        Debug.Log($"Deeplink: {deeplink ?? "null"}");
        Debug.Log($"Passthrough: {passthrough ?? "null"}");
        Debug.Log($"Is Deferred: {isDeferred}");

        // Handle deep link routing
        if (!string.IsNullOrEmpty(deeplink))
        {
            HandleDeepLink(deeplink, isDeferred);
        }
    }

    private void HandleDeepLink(string url, bool isDeferred)
    {
        // Your deep link routing logic here
        Debug.Log($"Routing to: {url} (Deferred: {isDeferred})");

        // Example: Parse the URL and navigate to the appropriate screen
        // if (url.Contains("product"))
        // {
        //     NavigateToProduct(url);
        // }
    }
}

Handler Behavior

Understanding SingularLinkHandler Execution

The SingularLinkHandler behaves differently depending on whether the app is freshly installed or already installed.

Fresh Install (Deferred Deep Link)

On a fresh install, no Open URL exists when the app launches. Singular completes attribution to determine if the tracking link contained a deep link or deferred deep link value.

Deferred Deep Link Flow:

1. User clicks a Singular tracking link configured with a deep link value
2. User installs and opens the app for the first time
3. Singular SDK sends the first session to Singular servers
4. Attribution completes and identifies the deep link from the tracking link
5. Deep link value returns to the SingularLinkHandler in the deeplink parameter with isDeferred = true

Already Installed (Immediate Deep Link)

When the app is already installed, clicking a Singular Link opens the app immediately using Universal Links (iOS) or Android App Links technology.

Immediate Deep Link Flow:

1. User clicks a Singular tracking link
2. The operating system provides an Open URL containing the entire Singular tracking link
3. During SDK initialization, Singular parses the URL
4. Singular extracts the deeplink and passthrough values
5. Values return through the SingularLinkHandler with isDeferred = false

Passthrough Parameters

Capture additional data from the tracking link click using passthrough parameters.

If a passthrough (_p) parameter is included in the tracking link, the SingularLinkHandler's passthrough parameter contains the corresponding data. Use this for capturing campaign metadata, user segmentation data, or any custom information you need in the app.

Forward All Query Parameters

Capture all query parameters from the tracking link URL by appending the _forward_params=2 parameter.

When _forward_params=2 is added to the tracking link, all query parameters are included in the deeplink parameter of the SingularLinkHandler, giving you access to the complete URL with all its parameters.