iOS SDK: Implementing Deep-Links

Singular iOS SDK
Singular iOS SDK version 9.2.4

iOS 8+

Sample App Review our sample app for an example of a complete SDK integration based on best practices.
Integration Guides
  1. Basic Integration
  2. Tracking Events and Revenue
  3. Implementing Deep-Links
  4. Advanced Options



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.


  • This article assumes your organization is using Singular Links - Singular's new tracking link technology, launched in 2019. Older customers of Singular may be using Singular's older tracking links (legacy links). To support deep-linking with legacy links, see Handling Deep-Links with Legacy Links.
  • The deep-link destinations for your app need to be set up on the Apps page in Singular (see Configuring Deep-Link URLs).

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.


- (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:


// 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.

registerDeferredDeepLinkHandler Method
Description Create a handler to read and process deep-links and deferred deep-links.
Signature + (void)registerDeferredDeepLinkHandler:(void (^)(NSString *deeplink))handler
Usage Example


- (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 }


  • You must register the handler before calling Singular startSession.
  • For optimal performance, we recommend placing Singular startSession calls before other processes/library initializations.
  • The block is called in the context of the main thread, so do not perform long-running operations inside the block.
  • If the Singular SDK does not receive a deep-link value within 5 seconds, the SDK calls the block and passes a null value.

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;
Was this article helpful?
0 out of 0 found this helpful