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 processAndResolve(_:withCompletionHandler:) 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)processAndResolveDeeplink:(nonnull ADJDeeplink *)deeplink
            withCompletionHandler:(nonnull ADJResolvedDeeplinkBlock)completion;

Process deep link (legacy)

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

+ (void)processDeeplink:(ADJDeeplink *)deeplink;

However, the processAndResolve(_:withCompletionHandler:) 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 your 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
  // Create deep link object
14
  guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
15

16
  // Send deep link to Adjust's servers for attribution.
17
  // If short branded link, receive long link.
18
  // Otherwise, receive original link.
19
  Adjust.processAndResolve(deeplink) { resolvedLink in
20
    // Handle failure if resolvedLink is nil
21
    guard let resolvedLink = resolvedLink else { return }
22

23
    // TODO: Handle resolvedLink by parsing its components
24
    // (example: path, query parameters) and
25
    // navigating to the appropriate screen.
26
  }
27

28
  return true
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
func application(
35
  _ application: UIApplication,
36
  open incomingLink: URL,
37
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
38
) -> Bool {
39
  // Create deep link object
40
  guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
41

42
  // Send deep link to Adjust's servers for attribution.
43
  // If short branded link, receive long link.
44
  // Otherwise, receive original link.
45
  Adjust.processAndResolve(deeplink) { resolvedLink in
46
    // Handle failure if resolvedLink is nil
47
    guard let resolvedLink = resolvedLink else { return }
48

49
    // TODO: Handle resolvedLink by parsing its components
50
    // (example: path, query parameters) and
51
    // navigating to the appropriate screen.
52
  }
53
  return true
54
}

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
  // Create deep link object
19
  ADJDeeplink *deeplink = [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
20
  if (!deeplink) return YES;
21

22
  // Send deep link to Adjust's servers for attribution.
23
  // If short branded link, receive long link.
24
  // Otherwise, receive original link.
25
  [Adjust processAndResolveDeeplink:deeplink
26
              withCompletionHandler:^(NSString *resolvedLink) {
27
                // Handle failure if resolvedLink is nil
28
                if (!resolvedLink) return;
29

30
                // TODO: Handle resolvedLink by parsing its components
31
                // (example: path, query parameters) and
32
                // navigating to the appropriate screen.
33
              }];
34

35
  return YES;
36
}
37

38
// Receive app scheme deep link when app is installed
39
// and link opens app from "not running",
40
// background, or foreground state.
41
- (BOOL)application:(UIApplication *)application
42
            openURL:(NSURL *)incomingLink
43
            options:
44
                (NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
45
  // Create deep link object
46
  ADJDeeplink *deeplink = [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
47
  if (!deeplink) return YES;
48

49
  // Send deep link to Adjust's servers for attribution.
50
  // If short branded link, receive long link.
51
  // Otherwise, receive original link.
52
  [Adjust processAndResolveDeeplink:deeplink
53
              withCompletionHandler:^(NSString *resolvedLink) {
54
                // Handle failure if resolvedLink is nil
55
                if (!resolvedLink) return;
56

57
                // TODO: Handle resolvedLink by parsing its components
58
                // (example: path, query parameters) and
59
                // navigating to the appropriate screen.
60
              }];
61
  return YES;
62
}

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
    // Create deep link object
14
    guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
15

16
    // Send deep link to Adjust's servers for attribution.
17
    // If short branded link, receive long link.
18
    // Otherwise, receive original link.
19
    Adjust.processAndResolve(deeplink) { resolvedLink in
20
      // Handle failure if resolvedLink is nil
21
      guard let resolvedLink = resolvedLink else { return }
22

23
      // TODO: Handle resolvedLink by parsing its components
24
      // (example: path, query parameters) and
25
      // navigating to the appropriate screen.
26
    }
27
    return
28
  }
29

30
  // Receive incoming app scheme deep link
31
  guard let incomingLink = connectionOptions.urlContexts.first?.url else { return }
32

33
  // Create deep link object
34
  guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
35

36
  // Send deep link to Adjust's servers for attribution.
37
  // If short branded link, receive long link.
38
  // Otherwise, receive original link.
39
  Adjust.processAndResolve(deeplink) { resolvedLink in
40
    // Handle failure if resolvedLink is nil
41
    guard let resolvedLink = resolvedLink else { return }
42

43
    // TODO: Handle resolvedLink by parsing its components
44
    // (example: path, query parameters) and
45
    // navigating to the appropriate screen.
46
  }
47
}
48

49
// Receive universal link when app is installed
50
// and link opens app from background state.
51
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
52
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
53
    let incomingLink = userActivity.webpageURL
54
  else { return }
55

56
  // Create deep link object
57
  guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
58

59
  // Send deep link to Adjust's servers for attribution.
60
  // If short branded link, receive long link.
61
  // Otherwise, receive original link.
62
  Adjust.processAndResolve(deeplink) { resolvedLink in
63
    // Handle failure if resolvedLink is nil
64
    guard let resolvedLink = resolvedLink else { return }
65

66
    // TODO: Handle resolvedLink by parsing its components
67
    // (example: path, query parameters) and
68
    // navigating to the appropriate screen.
69
  }
70
}
71

72
// Receive app scheme deep link when app is installed
73
// and link opens app from background
74
// or foreground state.
75
func scene(
76
  _ scene: UIScene,
77
  openURLContexts URLContexts: Set<UIOpenURLContext>
78
) {
79
  guard let incomingLink = URLContexts.first?.url else { return }
80

81
  // Create deep link object
82
  guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
83

84
  // Send deep link to Adjust's servers for attribution.
85
  // If short branded link, receive long link.
86
  // Otherwise, receive original link.
87
  Adjust.processAndResolve(deeplink) { resolvedLink in
88
    // Handle failure if resolvedLink is nil
89
    guard let resolvedLink = resolvedLink else { return }
90

91
    // TODO: Handle resolvedLink by parsing its components
92
    // (example: path, query parameters) and
93
    // navigating to the appropriate screen.
94
  }
95
}

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

15
      // Create deep link object
16
      ADJDeeplink *deeplink =
17
          [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
18
      if (!deeplink) return;
19

20
      // Send deep link to Adjust's servers for attribution.
21
      // If short branded link, receive long link.
22
      // Otherwise, receive original link.
23
      [Adjust processAndResolveDeeplink:deeplink
24
                  withCompletionHandler:^(NSString *resolvedLink) {
25
                    // Handle failure if resolvedLink is nil
26
                    if (!resolvedLink) return;
27

28
                    // TODO: Handle resolvedLink by parsing its components
29
                    // (example: path, query parameters) and
30
                    // navigating to the appropriate screen.
31
                  }];
32
      return;
33
    }
34
  }
35

36
  // Receive app scheme deep link
37
  if (connectionOptions.URLContexts.count == 0) return;
38

39
  UIOpenURLContext *urlContext =
40
      connectionOptions.URLContexts.allObjects.firstObject;
41
  NSURL *incomingLink = urlContext.URL;
42

43
  // Create deep link object
44
  ADJDeeplink *deeplink = [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
45
  if (!deeplink) return;
46

47
  // Send deep link to Adjust's servers for attribution.
48
  // If short branded link, receive long link.
49
  // Otherwise, receive original link.
50
  [Adjust processAndResolveDeeplink:deeplink
51
              withCompletionHandler:^(NSString *resolvedLink) {
52
                // Handle failure if resolvedLink is nil
53
                if (!resolvedLink) return;
54

55
                // TODO: Handle resolvedLink by parsing its components
56
                // (example: path, query parameters) and
57
                // navigating to the appropriate screen.
58
              }];
59
}
60

61
// Receive universal link when app is installed
62
// and link opens app from background state.
63
- (void)scene:(UIScene *)scene
64
    continueUserActivity:(NSUserActivity *)userActivity {
65
  // Check if it's a web browsing activity
66
  if (![userActivity.activityType
67
          isEqualToString:NSUserActivityTypeBrowsingWeb])
68
    return;
69

70
  // Check if there's a valid URL
71
  NSURL *incomingLink = userActivity.webpageURL;
72
  if (!incomingLink) return;
73

74
  // Create deep link object
75
  ADJDeeplink *deeplink = [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
76
  if (!deeplink) return;
77

78
  // Send deep link to Adjust's servers for attribution.
79
  // If short branded link, receive long link.
80
  // Otherwise, receive original link.
81
  [Adjust processAndResolveDeeplink:deeplink
82
              withCompletionHandler:^(NSString *resolvedLink) {
83
                // Handle failure if resolvedLink is nil
84
                if (!resolvedLink) return;
85

86
                // TODO: Handle resolvedLink by parsing its components
87
                // (example: path, query parameters) and
88
                // navigating to the appropriate screen.
89
              }];
90
}
91

92
// Receive app scheme deep link when app is installed
93
// and link opens app from background
94
// or foreground state.
95
- (void)scene:(UIScene *)scene
96
    openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
97
  // Check if we have any URL contexts
98
  UIOpenURLContext *urlContext = URLContexts.allObjects.firstObject;
99
  if (!urlContext) return;
100

101
  // Check if the URL is valid
102
  NSURL *incomingLink = urlContext.URL;
103
  if (!incomingLink) return;
104

105
  // Create deep link object
106
  ADJDeeplink *deeplink = [[ADJDeeplink alloc] initWithDeeplink:incomingLink];
107
  if (!deeplink) return;
108

109
  // Send deep link to Adjust's servers for attribution.
110
  // If short branded link, receive long link.
111
  // Otherwise, receive original link.
112
  [Adjust processAndResolveDeeplink:deeplink
113
              withCompletionHandler:^(NSString *resolvedLink) {
114
                // Handle failure if resolvedLink is nil
115
                if (!resolvedLink) return;
116

117
                // TODO: Handle resolvedLink by parsing its components
118
                // (example: path, query parameters) and
119
                // navigating to the appropriate screen.
120
              }];
121
}

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 AdjustSdk
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
          // Create deep link object
16
          guard let deeplink = ADJDeeplink(deeplink: incomingLink) else { return false }
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.processAndResolve(deeplink) { resolvedLink in
22
            // Handle failure if resolvedLink is nil
23
            guard let resolvedLink = resolvedLink else { return }
24

25
            // TODO: Handle resolvedLink by parsing its components
26
            // (example: path, query parameters) and
27
            // navigating to the appropriate screen.
28
          }
29
        }
30
    }
31
  }
32
}

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.