Set up direct deep linking

When a user with your app installed clicks an Adjust link, direct deep linking ensures they’re taken directly to specific content within the app.

Setup

iOS provides several methods for receiving direct deep links depending on your app’s implementation.

Within these methods, you’ll pass the deep link to the Adjust SDK using one of the following methods:

Process and resolve deep link (recommended)

Use the processDeeplink(_:completionHandler:) method, which does the following:

Records attribution from deep link clicks
Resolves short branded links to their long branded link equivalent
Passes through all other links as is

Your app can then handle the resolved link by parsing it and navigating to the appropriate screen. You can use this method for all deep links, including Adjust long branded links, other universal links, and app scheme deep links.

+ (void)processDeeplink:(nonnull NSURL *)deeplink
      completionHandler:(void (^_Nonnull)(NSString * _Nonnull resolvedLink))completionHandler;

Process deep link (legacy)

The Adjust SDK has the method, appWillOpen(_:), which can record attribution from deep link clicks if you’re not using short branded links.

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

However, the processDeeplink(_:completionHandler:) method supersedes the functionality of this legacy method, so it’s recommended to use this newer method.

Important Implementation Notes

Follow these deep link handling best practices:

Link Handling Requirements
- Your app should handle Adjust branded links (brandname.go.link) and universal links (example.com) identically. If your app uses a domain allowlist, ensure your Adjust branded domain is included. For example, both of the following should navigate to the same screen:
  - Adjust branded link: https://brandname.go.link/summer-clothes?promo=beach
  - Universal link: https://example.com/summer-clothes?promo=beach
- Your app should handle Adjust branded links and app scheme deep links identically. In cases where iOS doesn’t support universal links, Adjust converts them to the equivalent app scheme format. For example, both of the following should navigate to the same screen:
  - Adjust branded link: https://brandname.go.link/summer-clothes?promo=beach
  - App scheme deep link: example://summer-clothes?promo=beach
App State Considerations
- Ensure your app correctly handles links when they open the app from any state: “not running”, background, or if applicable, foreground.
- Consider storing deep links if they can’t be handled immediately, such as when the user isn’t yet authenticated, and process them once the app is ready for navigation.
In-App Navigation
- When an app tries to open its own universal links by calling UIApplication.open(_:options:completionHandler:) or SwiftUI’s openURL, iOS opens them in Safari instead of the app. To use these methods for internal navigation, you can only pass app scheme deep links to them. Alternatively, you can place universal links within your app and use your deep link handling logic to parse them and navigate to the appropriate screen.

Implementation

Use the implementation that aligns with your app’s structure:

UIKit apps using AppDelegate lifecycle
UIKit apps using SceneDelegate lifecycle
SwiftUI apps using AppDelegate lifecycle
SwiftUI apps using SceneDelegate lifecycle

UIKit apps using AppDelegate lifecycle

Update your AppDelegate to implement iOS direct deep linking methods.

Swift
Objective-C

1
// Receive universal link when app is installed
2
// and link opens app from "not running"
3
// or background state.
4
func application(
5
  _ application: UIApplication,
6
  continue userActivity: NSUserActivity,
7
  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
8
) -> Bool {
9
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
10
    let incomingLink = userActivity.webpageURL
11
  else { return true }
12

13
  // Send deep link to Adjust's servers for attribution.
14
  // If short branded link, receive long link.
15
  // Otherwise, receive original link.
16
  Adjust.processDeeplink(incomingLink) { resolvedLink in
17
    // TO DO: Handle resolvedLink by parsing its components
18
    // (example: path, query parameters) and
19
    // navigating to the appropriate screen.
20
  }
21

22
  return true
23
}
24

25
// Receive app scheme deep link when app is installed
26
// and link opens app from "not running",
27
// background, or foreground state.
28
func application(
29
  _ application: UIApplication,
30
  open incomingLink: URL,
31
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
32
) -> Bool {
33
  // Send deep link to Adjust's servers for attribution.
34
  // If short branded link, receive long link.
35
  // Otherwise, receive original link.
36
  Adjust.processDeeplink(incomingLink) { resolvedLink in
37
    // TO DO: Handle resolvedLink by parsing its components
38
    // (example: path, query parameters) and
39
    // navigating to the appropriate screen.
40
  }
41
  return true
42
}

1
// Receive universal link when app is installed
2
// and link opens app from "not running"
3
// or background state.
4
- (BOOL)application:(UIApplication *)application
5
    continueUserActivity:(NSUserActivity *)userActivity
6
      restorationHandler:
7
          (void (^)(NSArray<id<UIUserActivityRestoring>> *_Nullable))
8
              restorationHandler {
9
  // Check if it's a web browsing activity
10
  if (![userActivity.activityType
11
          isEqualToString:NSUserActivityTypeBrowsingWeb])
12
    return YES;
13

14
  // Check if there's a valid URL
15
  NSURL *incomingLink = userActivity.webpageURL;
16
  if (!incomingLink) return YES;
17

18
  // Send deep link to Adjust's servers for attribution.
19
  // If short branded link, receive long link.
20
  // Otherwise, receive original link.
21
  [Adjust processDeeplink:incomingLink
22
        completionHandler:^(NSString *resolvedLink){
23
            // TO DO: Handle resolvedLink by parsing its components
24
            // (example: path, query parameters) and
25
            // navigating to the appropriate screen.
26
        }];
27

28
  return YES;
29
}
30

31
// Receive app scheme deep link when app is installed
32
// and link opens app from "not running",
33
// background, or foreground state.
34
- (BOOL)application:(UIApplication *)application
35
            openURL:(NSURL *)incomingLink
36
            options:
37
                (NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
38
  // Send deep link to Adjust's servers for attribution.
39
  // If short branded link, receive long link.
40
  // Otherwise, receive original link.
41
  [Adjust processDeeplink:incomingLink
42
        completionHandler:^(NSString *resolvedLink){
43
            // TO DO: Handle resolvedLink by parsing its components
44
            // (example: path, query parameters) and
45
            // navigating to the appropriate screen.
46
        }];
47
  return YES;
48
}

UIKit apps using SceneDelegate lifecycle

Update your SceneDelegate to implement iOS direct deep linking methods.

Swift
Objective-C

1
// Receive universal link or app scheme deep link when app is installed
2
// and link opens app from "not running" state.
3
func scene(
4
  _ scene: UIScene,
5
  willConnectTo session: UISceneSession,
6
  options connectionOptions: UIScene.ConnectionOptions
7
) {
8
  // Receive incoming universal link
9
  if let userActivity = connectionOptions.userActivities.first,
10
    userActivity.activityType == NSUserActivityTypeBrowsingWeb,
11
    let incomingLink = userActivity.webpageURL
12
  {
13
    // Send deep link to Adjust's servers for attribution.
14
    // If short branded link, receive long link.
15
    // Otherwise, receive original link.
16
    Adjust.processDeeplink(incomingLink) { resolvedLink in
17
      // TO DO: Handle resolvedLink by parsing its components
18
      // (example: path, query parameters) and
19
      // navigating to the appropriate screen.
20
    }
21
    return
22
  }
23

24
  // Receive incoming app scheme deep link
25
  guard let incomingLink = connectionOptions.urlContexts.first?.url else { return }
26

27
  // Send deep link to Adjust's servers for attribution.
28
  // If short branded link, receive long link.
29
  // Otherwise, receive original link.
30
  Adjust.processDeeplink(incomingLink) { resolvedLink in
31
    // TO DO: Handle resolvedLink by parsing its components
32
    // (example: path, query parameters) and
33
    // navigating to the appropriate screen.
34
  }
35
}
36

37
// Receive universal link when app is installed
38
// and link opens app from background state.
39
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
40
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
41
    let incomingLink = userActivity.webpageURL
42
  else { return }
43

44
  // Send deep link to Adjust's servers for attribution.
45
  // If short branded link, receive long link.
46
  // Otherwise, receive original link.
47
  Adjust.processDeeplink(incomingLink) { resolvedLink in
48
    // TO DO: Handle resolvedLink by parsing its components
49
    // (example: path, query parameters) and
50
    // navigating to the appropriate screen.
51
  }
52
}
53

54
// Receive app scheme deep link when app is installed
55
// and link opens app from background
56
// or foreground state.
57
func scene(
58
  _ scene: UIScene,
59
  openURLContexts URLContexts: Set<UIOpenURLContext>
60
) {
61
  guard let incomingLink = URLContexts.first?.url else { return }
62

63
  // Send deep link to Adjust's servers for attribution.
64
  // If short branded link, receive long link.
65
  // Otherwise, receive original link.
66
  Adjust.processDeeplink(incomingLink) { resolvedLink in
67
    // TO DO: Handle resolvedLink by parsing its components
68
    // (example: path, query parameters) and
69
    // navigating to the appropriate screen.
70
  }
71
}

1
// Receive universal link or app scheme deep link when app is installed
2
// and link opens app from "not running" state.
3
- (void)scene:(UIScene *)scene
4
    willConnectToSession:(UISceneSession *)session
5
                 options:(UISceneConnectionOptions *)connectionOptions {
6
  // Receive universal link
7
  if (connectionOptions.userActivities.count > 0) {
8
    NSUserActivity *userActivity =
9
        connectionOptions.userActivities.allObjects.firstObject;
10
    if ([userActivity.activityType
11
            isEqualToString:NSUserActivityTypeBrowsingWeb] &&
12
        userActivity.webpageURL) {
13
      NSURL *incomingLink = userActivity.webpageURL;
14
      // Send deep link to Adjust's servers for attribution.
15
      // If short branded link, receive long link.
16
      // Otherwise, receive original link.
17
      [Adjust processDeeplink:incomingLink
18
            completionHandler:^(NSString *resolvedLink){
19
                // TO DO: Handle resolvedLink by parsing its components
20
                // (example: path, query parameters) and
21
                // navigating to the appropriate screen.
22
            }];
23
      return;
24
    }
25
  }
26

27
  // Receive app scheme deep link
28
  if (connectionOptions.URLContexts.count == 0) return;
29

30
  UIOpenURLContext *urlContext =
31
      connectionOptions.URLContexts.allObjects.firstObject;
32
  NSURL *incomingLink = urlContext.URL;
33

34
  // Send deep link to Adjust's servers for attribution.
35
  // If short branded link, receive long link.
36
  // Otherwise, receive original link.
37
  [Adjust processDeeplink:incomingLink
38
        completionHandler:^(NSString *resolvedLink){
39
            // TO DO: Handle resolvedLink by parsing its components
40
            // (example: path, query parameters) and
41
            // navigating to the appropriate screen.
42
        }];
43
}
44

45
// Receive universal link when app is installed
46
// and link opens app from background state.
47
- (void)scene:(UIScene *)scene
48
    continueUserActivity:(NSUserActivity *)userActivity {
49
  // Check if it's a web browsing activity
50
  if (![userActivity.activityType
51
          isEqualToString:NSUserActivityTypeBrowsingWeb])
52
    return;
53

54
  // Check if there's a valid URL
55
  NSURL *incomingLink = userActivity.webpageURL;
56
  if (!incomingLink) return;
57

58
  // Send deep link to Adjust's servers for attribution.
59
  // If short branded link, receive long link.
60
  // Otherwise, receive original link.
61
  [Adjust processDeeplink:incomingLink
62
        completionHandler:^(NSString *resolvedLink){
63
            // TO DO: Handle resolvedLink by parsing its components
64
            // (example: path, query parameters) and
65
            // navigating to the appropriate screen.
66
        }];
67
}
68

69
// Receive app scheme deep link when app is installed
70
// and link opens app from background
71
// or foreground state.
72
- (void)scene:(UIScene *)scene
73
    openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
74
  // Check if we have any URL contexts
75
  UIOpenURLContext *urlContext = URLContexts.allObjects.firstObject;
76
  if (!urlContext) return;
77

78
  // Check if the URL is valid
79
  NSURL *incomingLink = urlContext.URL;
80
  if (!incomingLink) return;
81

82
  // Send deep link to Adjust's servers for attribution.
83
  // If short branded link, receive long link.
84
  // Otherwise, receive original link.
85
  [Adjust processDeeplink:incomingLink
86
        completionHandler:^(NSString *resolvedLink){
87
            // TO DO: Handle resolvedLink by parsing its components
88
            // (example: path, query parameters) and
89
            // navigating to the appropriate screen.
90
        }];
91
}

SwiftUI apps using AppDelegate lifecycle

If you haven’t already done so, create an AppDelegate.swift file in your project’s main directory and reference it in your main application file, as shown in the example App.swift file below. This is required to handle app lifecycle events and Adjust SDK integration. Also, implement the onOpenURL SwiftUI modifier, which receives universal links and app scheme deep links when the app is installed.

Swift

1
import Adjust
2
import SwiftUI
3

4
@main
5
struct MyApp: App {
6
  @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
7

8
  var body: some Scene {
9
    WindowGroup {
10
      ContentView()
11
        // Receive universal link or app scheme deep link when app is installed
12
        // and link opens app from "not running",
13
        // background, or foreground state.
14
        .onOpenURL { incomingLink in
15
          // Send deep link to Adjust's servers for attribution.
16
          // If short branded link, receive long link.
17
          // Otherwise, receive original link.
18
          Adjust.processDeeplink(incomingLink) { resolvedLink in
19
            // TO DO: Handle resolvedLink by parsing its components
20
            // (example: path, query parameters) and
21
            // navigating to the appropriate screen.
22
          }
23
        }
24
    }
25
  }
26
}

SwiftUI apps using SceneDelegate lifecycle

Follow the instructions in the SwiftUI apps using AppDelegate lifecycle section. The onOpenURL SwiftUI modifier receives universal links and app scheme deep links when the app is installed and the link opens the app from a background or foreground state.

In addition, implement the scene(_:willConnectTo:options:) method from the UIKit apps using SceneDelegate lifecycle section. This method receives universal links and app scheme deep links when the app is installed and the link opens the app from a “not running” state.