Matching Platform


  1. Configuring your iOS app for 100% match from Safari
  2. Configuring your Android app for 100% match from Chrome
  3. Handling personally identifiable information

linkConfiguring your iOS app for 100% match from Safari

100% match is a bit of a misnomer, as it is only 100% match from when a user clicks from the Safari browser. According to our analysis, clicking through Safari happens about 50-75% of the time depending on the use case. For example, clicking from Facebook, Gmail or Chrome won’t trigger a 100% match here. However, it’s still beneficial to the matching accuracy, so we recommend employing it.

linkInclude SafariServices.framework

First off, you’ll need to include the SafariServices.framework into your app to leverage this. Currently, as soon as you add the Framework, Branch will start triggering the Safari-based 100% match technique. Note that this can be *disabled using the following method, which should be called before initSession.

[[Branch getInstance] disableCookieBasedMatching];

To add the framework, simply go to your Xcode project:

  • Select the right build target
  • Select the General tab
  • Scroll down to Linked Frameworks and Libraries
  • Click the + button
  • Add SafariServices.framework

linkRecommended: Display the SFSafariViewController to your user

With recent the change in Apple’s App Store policy, Apple requires that the Safari View Controller must be used to display information to users and cannot be loaded behind the scenes. Because of this, to use Branch’s Safari View Controller code, we highly recommend you comply with policy.

In showing a SafariViewController to your users, you likely are going to load a website with information on it. We’ve built some functionality that allows you load the Branch matching URL in your Safari View Controller and specify the URL for us to redirect to afterwards. Here is the recommended pathway:

1) Tell Branch to wait to initialize until you’ve displayed the Safari View Controller to the user. We recommend only doing this conditionally, since it will block the initialization of Branch in all cases until you call the corresponding resumeInit.

// Call this before initSession
[[Branch getInstance] enableDelayedInit];

2) Retrieve the 100% match URL from Branch by passing in the desired redirect URL. This will create a URL like It will quickly redirect from to the destination URL, displaying it in the view controller while simultaneously checking the cookie for Branch to do 100% matching.

NSURL *updatedUrlForOnboarding = [[Branch getInstance] getUrlForOnboardingWithRedirectUrl:[NSURL URLWithString:@""]];

3) Display your SFSafariViewController with the Branch matching URL. You can display the view controller any way that works with your particular application.

4) Catch the appropriate delegate method for the redirect or the loading complete and tell Branch it can resume initialization. This will call the Branch servers and return your deep link data with +match_guaranteed set to true if the cookies matched.

// Call this before initSession
[[Branch getInstance] resumeInit];

linkConfiguring your Android app for 100% match from Chrome

Similar to iOS, 100% match is a bit of a misnomer since this method will only work if a user clicks via the Chrome browser. Other browsers such as Facebook and Twitter will not benefit from this method. We haven’t pull the stats on usage like we do on iOS, but we’d assume it’s similar to Safari (50-75% of clicks).

linkEnable cookie matching

Add compile '' to the dependencies section of your build.gradle file.

linkSet the domain for cookie matching

Because our Chrome Tabs matching method works based on comparing the cookie Branch set on a click to the cookie set with the Chrome Tab, it’s critical that the domain match the link being clicked. By default, we assume that your domain is on the domain. If you want to override it, you must set the domain you want via a call to Branch like so:

// call before calling getAutoInstance in the Application class
Branch.enableCookieBasedMatching(""); // or "" if you use that

linkHandling personally identifiable information


Branch’s matching algorithm has not been designed to function as a security solution. We recommend against relying exclusively on Branch deep linking for authentication or authorization, and we advise against embedding sensitive or personally-identifiable information in Branch links.

Our advice is to ensure that users are not able to abuse your system if they are deep linked incorrectly to your app. Examples of use cases to avoid are:

  1. Automatically logging users into your app by including usernames and passwords in Branch links.
  2. Deep linking users to items they have purchased, or allowing them to change the state of their order without having them log into your app first.
  3. Deep linking to explicit content.

In the event that you choose to move forward with a usecase that does include sensitive information in your Branch links, you should check for the +match_guaranteed: true key-value pair in your initial Branch session callback, prior to routing to the deep linked content. Matching methods that provide +match_guaranteed: true are discussed in the Methods with 100% match accuracy section above. Methods that return +match_guaranteed: false is discussed in Methods without 100% match accuracy.