1. SDK Integration Guide


  1. Get the SDK files
  2. Configure Xcode Project
  3. Start a Branch session
  4. Handle incoming links
  5. Recommended: Track in-app events
  6. Next steps

Before using the Branch SDK, you must first sign up for an account and complete the onboarding process.

linkGet the SDK files

With extensive use, the iOS SDK footprint is 180 kb.

linkInstall with CocoaPods

The recommended way to install the SDK is via CocoaPods:

  1. Add pod "Branch" to your podfile.
  2. Run pod install from the command line.
  3. Run pod update from the command line. This updates the pod to the latest version of the SDK.

linkInstall with Carthage

Alternatively, you could install the SDK via Carthage:

  1. Add github "BranchMetrics/iOS-Deferred-Deep-Linking-SDK" to your Cartfile.
  2. Run carthage update from the command line.
If you do not use CocoaPods or Carthage

You can install the SDK manually.

linkConfigure Xcode Project

linkAdd your Branch key

  1. Retrieve your Branch Key on the Settings page of the Branch dashboard.
  2. Add new rows to your info.plist file with the following values, with the String entry inside the Dictionary:
Key Type Value
branch_key Dictionary  
live String [key_live_xxxxxxxxxxxxxxx]

Add the Branch Key

linkRegister a URI scheme

Caution: You should also configure Universal Links

In iOS 9.2, Apple dropped support for URL scheme redirects. You must also enable Universal Links to get full functionality from Branch on iOS 9.2+.

Branch opens your app by using its URI scheme (yourapp://), which should be unique to your app.

  1. On the Link Settings page of the Branch dashboard, ensure that I have an iOS App is checked and iOS URI Scheme is filled.
  2. In Xcode: Click your project file, navigate to Targets > Info > URL Types, and add a new entry with your URI scheme.

URL Scheme Demo

linkStart a Branch session

A Branch session needs to be started every single time your app opens. We check to see if the user came from a link and if so, the callback method returns any deep link parameters for that link. Please note that the callback function is always called, even when the network is out.

  1. In Xcode, open your App.Delegate.m file.
  2. Add #import "Branch/Branch.h" at the top to import the Branch framework.
  3. Define and initialize Branch

Initialize the SDK

In didFinishLaunchingWithOptions, add the following snippet:

Branch *branch = [Branch getInstance];
[branch initSessionWithLaunchOptions:launchOptions andRegisterDeepLinkHandler:^(NSDictionary *params, NSError *error) {
    if (!error && params) {
        // 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
        // ... insert custom logic here ...
        NSLog(@"params: %@", params.description);

If you’re using Xcode 6.3 or newer, have imported the SDK, and are still seeing a “Branch.h file not found” or some other compiler error, please read this support article.

linkHandle incoming links

Finally, add these two new methods to your AppDelegate.m file. The first responds to URI scheme links. The second responds to Universal Links, but will not be active until you configure Universal Links.

// Respond to URI scheme links
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    // pass the url to the handle deep link call
    [[Branch getInstance]

    // do other deep link routing for the Facebook SDK, Pinterest SDK, etc
    return YES;

// Respond to Universal Links
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
    BOOL handledByBranch = [[Branch getInstance] continueUserActivity:userActivity];

    return handledByBranch;

With your app now able to respond to Branch links, you will want to set up deep link routing to start sending users to the correct places inside of your app.

linkRecommended: Track in-app events

In-app engagement and user value metrics are just as important as the click, install, and re-open metrics that Branch automatically provides. Branch has a fixed set of post-install events, like purchase, add to cart, and share, but you’re free to add your own as well. Best of all, you can attribute these actions back to each link, campaign, or channel. Check out that discussion here.

Track custom events in your app with a simple call to the Branch SDK:

[[Branch getInstance] userCompletedAction:"signup"];

To track purchases with Branch, add a sendCommerceEvent:metadata:withCompletion: call to be executed immediately after a purchase is complete:

BNCCommerceEvent *commerceEvent = [BNCCommerceEvent new];
commerceEvent.revenue = [NSDecimalNumber decimalNumberWithString:@"20.00"];
[[Branch getInstance] sendCommerceEvent:commerceEvent
                         withCompletion:^ (NSDictionary *response, NSError *error) {
    if (error) { /* handle error here */ }

Tracking commerce events gives you powerful insights on the Branch dashboard, as well as more options with Journeys. See the Revenue Analytics page for more.

For more information on tracking and configuring custom events, see the user value attribution guide.

linkNext steps

The Branch SDK is now integrated into your app, and you can use the Branch dashboard to track completed installs from Quick Links. However, this only scratches the surface of what is possible with Branch.

Here are some recommended next steps:

  • Enable Universal & App Links — traditional URI scheme links are no longer supported in many situations on iOS 9.2+, and are a less than ideal solution on new versions of Android. To get full functionality from your Branch links on iOS devices, you should enable Universal Links as soon as possible.
  • Learn about Creating Links in Apps — let your users share content and invite friends from inside your app.
  • Set up Deep Link Routing — send incoming visitors directly to specific content in your app based on the Branch link they opened.
  • Set up Custom Event Tracking if you skipped the step above — make in-app activity beyond clicks, installs, and opens — like purchases and signups — available for analysis in the dashboard.
  • Submit your app to the App Store and Google Play Store