Deep linking

If you use Adtrace tracker URLs with deep linking enabled, you can receive the deep link URL and its content in your app.

Users can open the URL whether or not your app is already installed:

Scenario	App installed?	Who delivers the deep link
Standard (direct)	Yes	iOS opens your app and delivers the link through universal links or a custom URL scheme.
Deferred	No	The user installs from the App Store first. iOS does not deliver deferred deep links automatically. The Adtrace SDK provides the deep link content after install.
Reattribution	Yes (re-engagement)	iOS delivers the link as in the standard flow. You also call appWillOpenUrl so Adtrace can attribute the re-engagement.

Initialize the SDK early

Initialize the Adtrace SDK in application:didFinishLaunchingWithOptions: / application(_:didFinishLaunchingWithOptions:). If you call appWillOpenUrl before the SDK is initialized, attribution data from the deep link is permanently lost. Queue the NSURL and call appWillOpenUrl after appDidLaunch if needed. See Getting started with the iOS SDK.

Typical integration order:

1. Set up standard deep linking (universal links or custom URL scheme).
2. Reattribute from deep links with appWillOpenUrl for re-engagement campaigns.
3. Handle deferred deep links with AdtraceDelegate if users may install after clicking the tracker URL.

Set up standard deep linking

If a user already has your app installed and opens an Adtrace tracker URL that includes deep link information, iOS can launch your app and deliver that deep link.

Universal links (iOS 9+, recommended)

Universal links are the recommended approach on modern iOS. Adtrace handles much of the universal link setup behind the scenes, but you must configure both the Adtrace panel and your Xcode project.

Setup steps

1. Enable universal links for your app in the Adtrace panel.
2. Enable Associated Domains for your app in the Apple Developer portal.
3. In Xcode, enable Associated Domains for your target and add the domain from the panel with the applinks: prefix. Remove the http:// or https:// prefix from the domain.
4. Handle the link in continueUserActivity and parse the webpageURL.
5. For re-engagement campaigns, call appWillOpenUrl with the URL.

Example: If the panel shows https://app.adtrace.io/your-domain, add this in Xcode Associated Domains:

applinks:app.adtrace.io/your-domain

Handle universal links

Override application:continueUserActivity:restorationHandler: in your app delegate. The universal link URL is in userActivity.webpageURL.

Objective-C

AppDelegate.m

- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
  restorationHandler:(void (^)(NSArray *))restorationHandler {
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        NSURL *url = userActivity.webpageURL;
        // Use url for your app logic
        [Adtrace appWillOpenUrl:url];
    }
    return YES;
}

Swift

AppDelegate.swift

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
       let url = userActivity.webpageURL {
        // Use url for your app logic
        Adtrace.appWillOpenUrl(url)
    }
    return true
}

Custom URL scheme (legacy)

On iOS 8 and earlier, and for apps that still use custom URL schemes, register a unique scheme in your app's Info.plist under URL types (CFBundleURLTypes), then handle application:openURL:options:.

Use the same scheme in your tracker URL's deep_link parameter (URL-encoded). For example, adtraceExample:// encoded as adtraceExample%3A%2F%2F.

Objective-C

AppDelegate.m

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    // url contains your deep link content
    [Adtrace appWillOpenUrl:url];
    return YES;
}

Swift

AppDelegate.swift

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    // url contains your deep link content
    Adtrace.appWillOpenUrl(url)
    return true
}

URL-encode tracker parameters

You must URL-encode the deep_link parameter value in the tracker URL. In your app, the value you receive is not encoded.

Convert universal link to custom scheme

If your app logic expects custom URL scheme format but the user arrives via a universal link, convert the URL with convertUniversalLink:scheme:.

Method signature

+ (NSURL *)convertUniversalLink:(NSURL *)url scheme:(NSString *)scheme;

Parameter	Type	Description
url	NSURL	The universal link URL from continueUserActivity.
scheme	NSString	Your custom URL scheme name (for example adtraceExample).

Example

Objective-C

NSURL *oldStyleDeeplink = [Adtrace convertUniversalLink:url scheme:@"adtraceExample"];

Swift

let oldStyleDeeplink = Adtrace.convertUniversalLink(url, scheme: "adtraceExample")

Reattribute from deep links

Adtrace supports re-engagement campaigns with deep links. When a user who already has your app installed opens a tracker URL with deep link content, call the Adtrace SDK so it can read new attribution data from the link and send it to the Adtrace backend.

Complete standard deep linking setup first, then add appWillOpenUrl wherever you handle incoming links.

Method signature

+ (void)appWillOpenUrl:(NSURL *)url;

Parameter	Type	Description
url	NSURL	The deep link URL from continueUserActivity or openURL.

Important

If you call appWillOpenUrl before [Adtrace appDidLaunch:] / Adtrace.appDidLaunch(...), attribution data from the deep link is permanently lost. Queue the URL and call appWillOpenUrl after the SDK has started.

The SDK inspects the URL for new attribution information. If it finds data, it forwards it to Adtrace for reattribution. Use Get attribution information to read updated attribution in your app.

Call appWillOpenUrl from your universal link or custom scheme handler (see examples above).

WebBridge apps

If your app uses WebBridge, you can call appWillOpenUrl from the WebView JavaScript bridge when a deep link is opened in the web layer:

Adtrace.appWillOpenUrl(deeplinkUrl);

Handle deferred deep links

Deferred deep linking applies when the user does not have your app installed. They open an Adtrace tracker URL with a deep_link, install the app from the App Store, then open it. iOS does not deliver that deep link natively. The Adtrace SDK provides the deep link content after install.

By default, the Adtrace SDK opens deferred deep links automatically. Implement AdtraceDelegate if you want to control whether the SDK opens the link.

The same AdtraceDelegate protocol is used for attribution and event and session callbacks. For full delegate setup, see Send callback information.

Delegate method

- (BOOL)adtraceDeeplinkResponse:(NSURL *)deeplink;

Return value	Behavior
YES / true	Let the Adtrace SDK open the deep link.
NO / false	Do not open it. Save the URL and handle navigation yourself if needed.

Set the delegate on your ADTConfig instance before appDidLaunch:

Objective-C

AppDelegate.m

@interface AppDelegate () <AdtraceDelegate>
@end

// In didFinishLaunchingWithOptions:
[adtraceConfig setDelegate:self];

- (BOOL)adtraceDeeplinkResponse:(NSURL *)deeplink {
    // deeplink contains deferred deep link content
    return YES; // or NO to handle it yourself
}

Swift

AppDelegate.swift

class AppDelegate: UIResponder, UIApplicationDelegate, AdtraceDelegate {
    // In application(_:didFinishLaunchingWithOptions:):
    adtraceConfig?.delegate = self

    func adtraceDeeplinkResponse(_ deeplink: URL?) -> Bool {
        // deeplink contains deferred deep link content
        return true // or false to handle it yourself
    }
}

The callback runs after the SDK receives a deferred deep link from the server and before opening it.

If you do not implement this method, the Adtrace SDK always tries to open the deep link by default.

Example: handle the link yourself

Return NO / false to prevent the SDK from launching the URL automatically:

Objective-C

- (BOOL)adtraceDeeplinkResponse:(NSURL *)deeplink {
  // Save deeplink and navigate when your UI is ready
  return NO;
}

Swift

func adtraceDeeplinkResponse(_ deeplink: URL?) -> Bool {
    // Save deeplink and navigate when your UI is ready
    return false
}

Related

• Send callback information
• Get attribution information
• Getting started with the iOS SDK
• iOS SDK README (deep linking)