iOS Universal links and App Referrals using BranchIO Integration

Illustration by undraw.co

What is Universal Linking?

From iOS 9+, Apple has introduced a new concept known as Universal linking and deprecated the traditional URL schemes. In the traditional approach, the developer needs to specify a URL scheme in info.plist file under URL Types:

When we hit demoApp:// in Safari or code using openWithUrl method the application gets launched. But with Universal linking, the application is directly associated with your website domain i.e. a single domain works both for the website and mobile app.

So when a user clicks on the universal link, the OS itself checks whether any app is associated with this domain or not. If it founds any domain linked to the app, then directed the app launch is triggered without any Safari routings and website redirects. If the app is not installed, OS opens the URL is safari for further routing.

Perform steps bellow to enable universal linking:

1. Enable Associated domain in Apple Member Center for your Bundle ID:

Sign in with your Apple ID

Note: To support app links, the keyword ‘applinks:’ must be before the domain.

Website Configuration:

The main part is apple-app-site-association file. It is a JSON file hosted on your site which contains details of your domain and bundles it mapping. Take a look at the Apple developer site for further details (check here).

App Referrals:

The referral is a feature in which a user sends an invite link to his/her friends, relatives etc and ask them to use this app. This is nothing but redirecting or diverting users towards the app.

In the referral program, a person who sends the invite links gets rewards which can be claimed by various means. Different rules can be applied like the user will get reward points only when a new user installs and completes the sign-up process etc. This where BranchIO comes into the picture, helping us to apply different rules.

BranchIO Setup using pods:

• In the pod file:

platform :ios, '10.0'target 'DEMOAPP' do
  use_frameworks!
  pod ‘Branch’, ‘~> 0.25.11’
end

then on the terminal — pod install.

Key configuration in the project:

• Copy the key from BranchIO dashboard from https://branch.io/.

By switching the toggle from Live to Test and vice-versa you can change the environment and its settings. Copy key from Account Settings -> Profile -> Branch Key and Secret.

• In info.plist add a key ‘branch_key’ with data type as ‘String’ if you have only one environment else as ‘Dictionary’ with two keys ‘live’ and ‘test’.

For only live key:

For live and test key:

• Add BranchIO link domain support:

1. Go to the Link Settings page on the dashboard. Scroll down to the Link Domain area. Copy your domain name. Here you can also check for a custom domain.

2. Switch to Capabilities tab, in domain section click on + to add new domain in below format. Make sure xxxx matches exactly to your domain.

• applinks:xxxx.app.link
• applinks:xxxx-alternate.app.link
• applinks:xxxx.test-app.link
• applinks:xxxx-alternate.test-app.link

Swift code configuration:

Firstly, import Branch.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
   let branch: Branch = Branch.getInstance()
 branch.initSession(launchOptions: launchOptions, andRegisterDeepLinkHandler: {params, error in
  if error == nil {
  // params are the deep linked params associated with the link that the user clicked -> was re-directed to this app
  // params will be empty if no data found
  // Logic handling
  print("params: %@", params as? [String: AnyObject] ?? {})
  }
})
}
func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool {
let branchHandled = Branch.getInstance().application(application, open: url, sourceApplication: sourceApplication, annotation: annotation)
 if (!branchHandled) {
  // If not handled by Branch, do other deep link routing for the   Facebook SDK, Pinterest SDK, etc
  }
 return true
}
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([Any]?) -> Void) -> Bool {
// pass the url to the handle deep link call
  Branch.getInstance().continue(userActivity)
 return true
}

Uniquely identify a user for tracking purpose on BranchIO:

Branch.getInstance()?.setIdentity(uniqueId)

Keep in mind that setIdentity() method should be used. It takes a unique param which will identify the user uniquely in your database. Such as email- Id, user-Id etc.

Branch IO dashboard configuration:

Live Settings:

On branch dashboard under link settings, tick iOS and enter below details:

• iOS Url Scheme: If the app is registered with some scheme then we need to specify here. When a referral/universal link is clicked then it will use scheme to launch the app.
• Apple Store Search: If the app is not installed then you can redirect the user to the App Store for that particular app. Search your app here by name.
• Custom URL: You can also redirect the user to a particular website instead of the App Store. This might be a case where either of one platform(iOS or Android) is supported and for the other, you want to redirect the user to a website for further communication.
• Bundle Id: Give the bundle id of the app.
• Apple App Prefix: The App prefix can be retrieved from app developer account or even from Xcode -> General -> Signing. It is just a Team Id.

Testing Settings:

In testing link settings has the same settings as Live for iOS URL Scheme, Apple Store Search, Custom Url etc.

Note: Let’s say you have two apple developer account, one for live and other for different environments. In this case mention respective app prefix w.r.t the bundle identifier. If your app has multiple bundle id support then mention all the identifiers by clicking on ‘Add New Bundle Id +’ button.

Dashboard event logging:

Under Setup & Testing -> Liveview, all the runtime events get logged here. BranchIO sdk supports few default ones, like install, open, reinstall and click.

Click on extreme right more icon to check other referred params like feature, developer identity, last attribution, OS etc.

Referrals Rule:

For referral from, go to section Referrals -> Reward Rules. Here you can set the rules for both referring users as well as referred acting users. Below I have set a rule in which both the user will get rewarded by 10 points every time for app open event.

Note: For iOS we need bundle ids in order to get Universal Links to work.
However, on Android in order to get the App Links to work, we only need the SHA256 Cert Fingerprints. Therefore, since we do not require the bundle ids on Android hence we do not ask for it either on the dashboard.

Also if you have multiple package name for a different environment like testing, staging etc, then Branch does not have support to accept more than one package name. Hence events will only get tracked for build having package name mentioned on the dashboard.

Thanks for reading and happy coding!