1. SDK Integration Guide


  1. Get the SDK files
  2. Configure Manifest
  3. Start a Branch session
  4. Recommended: Track in-app events
  5. 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 Android SDK footprint is 187 kb.

linkInstall with Gradle

Add compile 'io.branch.sdk.android:library:2.+' to the dependencies section of your build.gradle file.

linkAdd Google Play Services

To ensure full measurement and deferred deep linking, include the Google Play Services library in the same build.gradle file. Follow these steps to ensure you have added the Google Play Services library.

  1. Add compile 'com.google.android.gms:play-services-ads:9+' or greater version in your dependencies section.
  2. Add the following line in your Proguard settings:
-keep class com.google.android.gms.ads.identifier.** { *; }

You can also find the source and JAR file here.

Note that if you don’t plan to use the Fabric Answers integration, you can use the following line:

compile ('io.branch.sdk.android:library:2.+') {
  exclude module: 'answers-shim'
Android build errors

Occasionally, Android will barf after you add our library due to generic issues unrelated to Branch. Please see this advanced section

linkConfigure Manifest

linkAdd your Branch key

  1. Retrieve your Branch Key on the Settings page of the Branch dashboard.
  2. Open your AndroidManifest.xml and add the following <meta-data> tag:
    <!-- Other existing entries -->

    <meta-data android:name="io.branch.sdk.BranchKey" android:value="key_live_xxxxxxxxxxxxxxx" />

Internet Permissions

Your app needs to have internet permissions in order to communicate with the Branch service. Make sure you set <uses-permission android:name="android.permission.INTERNET" />

linkRegister for Google Play Install Referrer

Add this snippet to your AndroidManifest.xml:

<receiver android:name="io.branch.referral.InstallListener" android:exported="true">
    <action android:name="com.android.vending.INSTALL_REFERRER" />
Alternative Configuration

linkRegister a URI scheme

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 Android App is checked and Android URI Scheme is filled.
  2. Choose the Activity you want to open up when a link is clicked. This is typically your SplashActivity or a BaseActivity that all other activities inherit from.
  3. Inside your AndroidManifest.xml, locate where the selected Activity is defined.
  4. Within the Activity definition, insert the intent filter provided below. Change yourapp under android:scheme to the URI scheme you’ve selected.
  <data android:scheme="yourapp" android:host="open" />
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />

To ensure proper deep linking from other apps such as Facebook, this Activity must be launched in singleTask mode. This is done in the Activity definition as so:


linkEnable Auto Session Management

If your app uses a custom Application class, add Branch.getAutoInstance(this); so that it matches the following:

public final class CustomApplicationClass {
  public void onCreate() {
      // initialize the Branch object
Caution: Make sure this is the correct onCreate()!

Your Activity also has an onCreate() method. Be sure you do not mix the two up!

Alternative Configurations

linkOptimize Performance

By default, Branch will delay the install call only for up to 1.5 seconds. We delay the install call in order to capture the install referrer string passed through Google Play, which increases attribution and deferred deep linking accuracy. We do not delay any other call, and the install call only occurs the first time a user opens your app.

If we receive the referrer string before 1.5 seconds, we will immediately fire the call, meaning this delay is up to 1.5 seconds, but not guaranteed to take that long.

If you’d like to optimize the first install call, simply paste the following code in your Application class, and we will not delay the first install call.

public final class CustomApplicationClass {
  public void onCreate() {
      // initialize the Branch object

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.

Open the Activity for which you registered the Intent in the previous section, and hook into the onStart and onNewIntent lifecycle methods by adding these overrides:

public void onStart() {
    Branch branch = Branch.getInstance();

    branch.initSession(new Branch.BranchReferralInitListener(){
        public void onInitFinished(JSONObject referringParams, BranchError error) {
            if (error == null) {
                // 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 ...
            } else {
                Log.i("MyApp", error.getMessage());
    }, this.getIntent().getData(), this);

public void onNewIntent(Intent intent) {
If you are calling this method inside a fragment

this.getIntent().getData() refers to the data associated with an incoming intent. Please use getActivity() instead of passing in this.

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:


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

CommerceEvent commerceEvent = new CommerceEvent();
Branch.getInstance().sendCommerceEvent(commerceEvent, null, null);

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