1. SDK Integration Guide

Contents

  1. Get the SDK files
  2. Configure Manifest
  3. Start a Branch session
  4. Recommended: Track in-app events
  5. Next steps
Prerequisites

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.

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:
<application>
    <!-- Other existing entries -->

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

</application>
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">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>
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.
<intent-filter>
  <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" />
</intent-filter>

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 {
  @Override
  public void onCreate() {
      super.onCreate();
      // initialize the Branch object
      Branch.getAutoInstance(this);
  }
}
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

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:

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

    branch.initSession(new Branch.BranchReferralInitListener(){
        @Override
        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);
}

@Override
public void onNewIntent(Intent intent) {
    this.setIntent(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:

Branch.getInstance(getApplicationContext()).userCompletedAction(BranchEvent.SHARE_STARTED);

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 Marketing 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