Introduction

Deep-links are links that lead into specific content inside an app. When a user clicks a deep-link on a device that has the app installed, the app opens and shows a specific product or experience.

Singular tracking links can include deep-linking as well as deferred deep-linking (see our Deep-Linking FAQ and the Singular Links FAQ for more information).

The instructions below will show you how to:

1. Access the tracking link that led to your app being opened,
2. Read the deep-link destination, and
3. Show the appropriate content.

Deep-Linking Prerequisites

Singular uses iOS Universal Links for deep-linking.

To enable Universal Links, follow the instructions in Singular Links Prerequisites.

Handling Deep-Links

The Singular SDK offers deep-link support through a handler that you set when you initialize the Singular SDK.

First, create the callback method for the handler. In the example below, we create a callback method called processDeeplink. The block signature is: void(^)(SingularLinkParams*). The SingularLinkParams contains the deep-link destination, passthrough parameters, and whether the link is deferred or not.

Objective-C:

- (void)processDeeplink:(SingularLinkParams *)params {
    NSString* deeplink = [params getDeepLink];
    NSString* passthrough = [params getPassthrough];
    BOOL isDeferredDeeplink = [params isDeferred];
    // Add your code here
}

Then add a call to the SDK initialization method, including withSingularLinkHandler and your callback method, in both the didFinishLaunchingWithOptions and continueUserActivity entry points of your AppDelegate:

Objective-C:

// didFinishLaunchingWithOptions
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Singular startSession:@"YourAPIKey" withKey:@"YourAPISecret"
    andLaunchOptions:launchOptions
    withSingularLinkHandler:^(SingularLinkParams * params) {
        [self processDeeplink:params];
    }];
    return YES;
}

// continueUserActivity
- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>>
    *restorableObjects))restorationHandler {
    [Singular startSession:@"YourAPIKey" withKey:@"YourAPISecret"
    andUserActivity:userActivity
    withSingularLinkHandler:^(SingularLinkParams * params) {
        [self processDeeplink:params];
    }];
    return YES;
}

Handling Deep-Links with Legacy Links

If you are an older Singular customer, you may be using legacy tracking links (Singular's older tracking link mechanism) rather than the newer Singular Links. Legacy links are managed in the Create Link and View Links pages, and they also provide deep-linking and deferred deep-linking functionality.

If your organization uses legacy links, you can implement deep-linking (and deferred deep-linking) support through a different handler, registered using registerDeferredDeepLinkHandler.

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     // Register the handler
    [Singular registerDeferredDeepLinkHandler:^(NSString
        *deeplink) {    
        NSLog(@"Deep-link from Singular: %@", deeplink);
        [self processDeeplink:deeplink];
    }];
    return YES;
}

- (void)applicationDidBecomeActive:(UIApplication *)application {     
    [Singular startSession:@"MyID" withKey:@"MyKey"];
}

// Callback method for the handler
- (void)processDeeplink:(NSString *)deeplink {
    // Implement your code here
}

Handling Deep-Links without Universal Links

The Singular SDK does provide support for Apple's older-style URI schema deep-links, if your app does not support Apple's Universal Links.

To support URI schema deep-links, add the following to the application function:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    [Singular startSession:@"yourAPIKey" withKey:@"yourSecret" andLaunchURL:url];
    return YES;
}