Branch Deeplink handling in iOS

What is Deeplink?

In the context of mobile app, deep link is a URL consisting of uniform resource identifier (URI) that links to a specific location within a mobile app rather than simply launching the app.

Why deep link?

• Promote mobile app through websites
• Best user experience
• Display marketing through ad banners
• Email marketing by engaging users with customized emails

Deferred deep link!!

Deferred deep linking is one of the aspects of mobile deep linking which describes the principle of deep linking into an app that is not yet installed. In this case, deep linking will be “deferred” until the application is installed by user. On clicking deferred deep link, it navigates to App Store/Play Store and after the installation of the app, it navigates to specific location inside the app. If app is already installed, it will directly launch the app opening the specific location inside the app.

Universal Links!!

From iOS 9, Apple has introduced Universal links. On clicking universal links, iOS checks if there is any installed app which supports the link and opens that corresponding application, or else that URL (link) will be opened in the web browser. (For users who are running versions of iOS earlier than 9.0, tapping a universal link opens the link in default web browser)

Integrate deferred deeplink in iOS using Branch SDK

Step 1: Install Branch SDK

• Using CocoaPods

platform :ios, '10.0'
target 'APP_NAME' do
  use_frameworks!
  pod 'Branch'
end

then run “pod install”

• Using Carthage

github "BranchMetrics/ios-branch-deep-linking"

• Manually install Branch using source code

1. Drag and drop Branch.framework into Embedded Binaries (select Copy items if needed)
2. Import AdSupport, SafariServices, MobileCoreServices, CoreSpotlight, and iAd into Linked Frameworks

Step 2: Enable associated domain

• Enable associated domain in target -> capabilities in the xcode project.
• Add associated domain functionality in the apple development provisioning profile.

Step 3: Configure Branch dashboard

Complete the following setup in Branch dashboard link settings.

1. Create unique URI scheme for your application e.g, myapp://
2. Select the respective iOS app if it’s already exists in play store or app store.
3. To enable universal links, add app’s bundle identifier and apple app prefix (You can find the apple app prefix in the apple developer account) in the dashboard.
4. You will find default link domain and alternate link domain at the end of the link settings. Add these two links prefixed with “applinks:” as the associated domains in the xcode project ; which will look like “applinks:myapp.test-app.link”. Save the changes in dashboard.

Four links which are added in the below image corresponds to both test and live projects.

Image 1

Step 4: Create Quick links

Go to Quick links in Branch dashboard.

1. Go to “Create link” at top right of the dashboard. Give your link a name. This name will appear in the dashboard for easy tracking. You can also give the corresponding web url.
2. A unique default name will be appended to your link domain. You can change this name if needed before creating the link. Once you create the link, you cannot change this name.
3. To handle these quick links in the mobile app, you can add key-value pairs in the deep linking settings. On clicking the link, you will get these key-value pairs in app completion block. For example, adding reference_id as 0 in deeplinking setting.
4. You can add tags for analytics. You can also associate an image for the link to share it in social sites.
5. Tap on “Create Link Now” to create the link.
6. You can share these links to user via email, Facebook or you can opt for any service provider. For testing purpose, you can paste these url in Notes or send an email.

Step 5: App setup

Add the following code in Appdelegate file in your project.

import Branch
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    setupBranchSDK(launchOptions: launchOptions)
}
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
    Branch.getInstance().application(app, open: url, options: options)
    return true
}
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
    Branch.getInstance().continue(userActivity)
    return true
}
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    Branch.getInstance().handlePushNotification(userInfo)
}
private func setupBranchSDK(launchOptions: [UIApplication.LaunchOptionsKey: Any]?) {
    #if DEBUG
    Branch.getInstance().setDebug()
    #endif
    Branch.getInstance().initSession(launchOptions: launchOptions) {        params, _ in
    if let params = params as? [String: AnyObject] {
        if let refId = params["reference_id"]?.integerValue {
            /// ******** handle deep linking here *********
        }
    }
}

In the Branch initSession closure you need to handle the navigation inside the app with respect to parameters.

On clicking the link, if app is not installed, it will redirect to App Store. After installing the app, Branch initSession closure will give all the associated key-value pairs.

If app is already installed, app will launch and Branch initSession closure will get called.

Integrate universal link in iOS using Branch SDK

Step 1 and step 2 are same as explained above.

Step 3: Configure Branch dashboard

Using Branch, if you need to use universal links, you need to enable one of the email service provider in the dashboard. Here I will explain using Cheetah digital as email service provider.

Goto Email -> cheetah digital in Branch dashboard and configure the setup.

1. Use the default settings, click next.
2. You will be asked to enter web url that corresponds to screen within your app. You can enter url or you can skip this step.
3. You will be prompted to enter CTD (Click Tracking Domain). Create your own domain like “email.example.com”. You need to communicate with the Branch team for hosting AASA file using CTD.
4. Generate your test link by inputting web url. Append “web_only=true” or “web_only=false” at the end of the url. Also you can append “reference_id” with some value for navigating to different screen inside the app.

Step 4: App setup

1. Add CTD prefixed with applinks: in the associated domain list (refer Image 1), which will look like “applinks:email.example.com”
2. Add all the methods which are mentioned in step 5 of Integrate deferred deeplink in iOS using Branch SDK.
3. In the Branch initSession method, check for “web_only” parameter. If it is true, check for original_url parameter and navigate to that url.

if let params = params as? [String: AnyObject] {
    // parameter check for cheetah web only handling
    if let webOnly = params["web_only"], webOnly.boolValue == true {
        if let urlString = params["original_url"] as? String, let url = URL(string: urlString) {
            UIApplication.shared.openBrowser(url)
            return
        }
    }
}

4. If web_only parameter is false, check for “reference_id”, if value presents, you can navigate to corresponding screen inside app.

5. On clicking the link, Branch init session closure will get called and you need to handle the navigation inside the app with respect to parameters.

!!! Hurray !!! Now, you have configured both deferred deeplink and universal link in your app.

Thanks for reading :)