Tracking Deep Links

When a user clicks a trackable link in a message, the SDK reports the click event.

info

The SDK is only responsible for tracking the click event. You must handle navigation to your app manually.

Tracking Deep Links in the SDK

1. Ensure that all steps from the requirements are carried out correctly.

2. Add deep links as trackable links in your emails.

3. Use UniversalLinks for iOS and URL schemes for Android as trackable links.

4. Process the deep links in your app.

   Android

   Deep link tracking is done automatically in most cases, with one exception. If your Activity overrides onNewIntent, call track:

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        EngagementCloud.deepLink.track(this, intent)
    }

   Kotlin Multiplatform

   To track deep links, call track with the URL:

   EngagementCloud.deepLink.track(url)

   url is the deep link URL string you want to track.

   iOS

   To track deep links, call track in your AppDelegate's application:continueUserActivity:restorationHandler: method:

   func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
        EngagementCloud.shared.deepLink.track(userActivity)
   }

   The Bool return value of EngagementCloud.shared.deepLink.track() indicates whether the UserActivity contained an SAP Engagement Cloud email deep link and whether it was handled by the SDK.

   userActivity is the UserActivity that comes from the AppDelegate’s application:continueUserActivity:restorationHandler: method.

   For more information, see the relevant iOS documentation.

   Web

   To track deep links, call track with a URL containing the ems_dl parameter:

   await window.EngagementCloud.deepLink.track(url);

   url represents the link you would like to track.

What Is Not Considered Deep Linking?

The term "deep link" is sometimes used broadly for any event or trigger that opens the application. In the SAP Engagement Cloud SDK, deep linking specifically refers to a user selecting a link that opens the app instead of the browser. The following actions are not considered deep linking.

push to app event

Using the SDK's rich notification feature, you can send a notification that contains an application event as the default action when the user triggers it. The registered push event handler is then called with the given name and payload parameters.

push to external url event

Using the SDK's rich notification feature, you can send a notification which contains a URL as the default action when the user triggers it. The URL is then opened outside the application.

inApp to app event

Using the SDK's in-app messaging feature, you can set an action in the in-app message that contains a name and a payload. When the user triggers it, the SDK calls the registered in-app event handler with the given name and payload parameters.

inApp to external url event

Using the SDK's in-app messaging feature, you can set an action in the in-app message that contains a URL. When the user triggers it, the URL is opened outside the application.

custom data fields

On the Mobile Engage / Push page, you can set custom data fields that are included in the push payload and can be extracted when the push payload arrives in the application.

Avoiding Duplicate Tracking

• Android: If Activity overrides onNewIntent, ensure you call deepLink.track exactly once.
• iOS: Only call inside the continue userActivity method for universal links (not every openURL callback).
• Web: Only track links containing ems_dl. Skip unrelated URLs.

Handling Errors

Android

val result = EngagementCloud.deepLink.track(this, intent)
// Returned status can indicate whether link belonged to Engagement Cloud domain.

Kotlin Multiplatform

val result = EngagementCloud.deepLink.track(url)
// Returned status can indicate whether link belonged to Engagement Cloud domain.

iOS

let handled = try? await EngagementCloud.shared.deepLink.track(userActivity)

Web

const handled = await window.EngagementCloud.deepLink.track(url);

Testing Recommendation

• Build sample universal links and app links in your staging environment.
• Use simulator and emulator logs to verify you get a single tracking call per user click.
• Inject deep links while the app is running in the background and foreground to test both paths.

Privacy Recommendations

• Do not treat deep link parameters as authenticated session data.
• Validate any tokens on the server side before performing privileged actions.