Singular iOS SDK | |
---|---|
Download |
Singular iOS SDK version 10.1.5 |
Compatibility | iOS 8+ |
Sample App |
Our sample app includes a complete integration of the Singular SDK. Review the code to see how the different parts of the integration come together using best practices. |
Integration Guides |
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:
- Access the tracking link that led to your app being opened,
- Read the deep link destination, and
- Show the appropriate content.
Notes:
- 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 (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.
Objective-C:
- (void)processDeeplink:(SingularLinkParams *)params {
NSString* deeplink = [params getDeepLink];
NSString* passthrough = [params getPassthrough];
BOOL isDeferredDeeplink = [params isDeferred];
// Add your code here
}
Next, add a call to the SDK initialization method:
-
If your app does NOT use scenes:
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; } // openUrl - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options{ SingularConfig* config = [[SingularConfig alloc] initWithApiKey:@"YourAPIKey" andSecret:@"YourAPISecret"]; config.singularLinksHandler = ^(SingularLinkParams * params) { [self processDeeplink:params]; }; config.openUrl = url; [Singular start:config]; return YES; }
-
If your app uses scenes:
- Add a call to the SDK initialization method, including withSingularLinkHandler and your callback method, in the didFinishLaunchingWithOptions and entry point 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; }
- Then call the SDK initialization method, including withSingularLinkHandler & andUserActivity, in both the willConnectToSession and continueUserActivity entry points of your SceneDelegate:
// willConnectToSession - (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions { NSUserActivity* userActivity = [[[connectionOptions userActivities] allObjects] firstObject]; if(userActivity){ [Singular startSession:@"YourAPIKey" withKey:@"YourAPISecret" andUserActivity:userActivity withSingularLinkHandler:^(SingularLinkParams * params) { [self processDeeplink:params]; }]; } } // continueUserActivity - (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity{ [Singular startSession:@"YourAPIKey" withKey:@"YourAPISecret" andUserActivity:userActivity withSingularLinkHandler:^(SingularLinkParams * params) { [self processDeeplink:params]; }]; } // openURLContexts - (void)scene:(UIScene *)scene openURLContexts:(nonnull NSSet<UIOpenURLContext *> *)URLContexts { NSURL *url = [[URLContexts allObjects] firstObject].URL; if(url){ SingularConfig* config = [[SingularConfig alloc] initWithApiKey:@"YourAPIKey" andSecret:@"YourAPISecret"]; config.singularLinksHandler = ^(SingularLinkParams * params) { [self processDeeplink:params]; }; config.openUrl = url; [Singular start:config]; } }
- Add a call to the SDK initialization method, including withSingularLinkHandler and your callback method, in the didFinishLaunchingWithOptions and entry point of your AppDelegate:
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 |
Objective-C:
|
Notes:
- 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 Non-Singular Deep Links
The Singular SDK provides support for handling non-Singular-served deep links, which is required for some measuring attributions for some partners, such as for Google Ads re-engagement campaigns types.
To support these 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;
}