Android Full Reference

Installation

The compiled Android SDK footprint is 187kb

Install Library Project

Just add implementation 'io.branch.sdk.android:library:5.+' to the dependencies section of your build.gradle file.

Some notes:

• If you don't plan to use the Fabric Answers integration, and don't want to import the answers-shim, just import your project as follows:

implementation ('io.branch.sdk.android:library:5+') {
  exclude module: 'answers-shim'
}

• This supports minimum sdk level 21.
• Android SDK versions 3.x and above communicate over TLS1.2.
• If you want to import the AAR directly, you can find the build in Nexus here: https://search.maven.org/artifact/io.branch.sdk.android/library.
• Or you can clone this repo and import the source as a library into your project

Register Your App

You can sign up for your own app id at https://dashboard.branch.io

Register an activity for direct deep linking (optional but recommended)

In your project's manifest file, you can register your app to respond to direct deep links (yourapp:// in a mobile browser) by adding the second intent filter block. Also, make sure to change yourapp to a unique string that represents your app name.

Secondly, make sure that this activity is launched as a singleTask. This is important to handle proper deep linking from other apps like Facebook.

Typically, you would register some sort of splash activitiy that handles routing for your app.

<activity
    android:name="com.yourapp.SplashActivity"
    android:label="@string/app_name"
    <!-- Make sure the activity is launched as "singleTask" -->
    android:launchMode="singleTask"
     >
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Add this intent filter below, and change yourapp to your app name -->
    <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>
</activity>

Leverage Android App Links for deep linking

If you are building applications targeting for Android M or above, Branch make it really easy to configure your app for deep linking using App Links. In your project's manifest file, you can register activities to for App Linking by adding an intent filter as follows.

If using app.link

With app.link, there's no need to use the encoded id and you just need to list the domains.

<activity android:name="com.yourapp.your_activity">
    <!-- App Link your activity to Branch links-->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
         <data android:scheme="https" android:host="yourapp-alternate.app.link" />
         <data android:scheme="https" android:host="yourapp.app.link" />
    </intent-filter>
</activity>

If using a custom domain

<activity android:name="com.yourapp.your_activity">
    <!-- App Link your activity to Branch links-->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="your.app.com"/>
    </intent-filter>
</activity>

That's all you need. Deep linked parameters associated with the link is passed through Branch initialization process.

📘

Note

While using App Links please make sure you have registered the Activity for deep linking using Branch URI scheme as discussed in the previous session inorder to get deep link work on previous versions of Android (which does not support App Links).

Deeplink via push notification

If you would like to support push notification based routing while your app already in foreground, please add the following to your notification intent.

intent.putExtra("branch_force_new_session",true);

Guaranteed Matching

Branch support hundred percent guaranteed matching with cookie based matching using Custom Chrome Tabs. This is highly recommended if you like to do user authentication through deep link metadata.
Just add the following to your build.gradle file to enable guaranteed matching

implementation 'com.android.support:customtabs:23.3.0'

📘

Note

Adding additional dependencies may overrun the dex limit and lead to NoClassDefFoundError or ClassNotFoundException. Please make sure you have enabled multi-dex support to solve this issue. For more information on enabling multi-dex support please refer to Troubleshooting

Configure your AndroidManifest.xml

📘

Note

Provide internet permission. Branch SDK need internet access to talk to Branch APIs.

Add your Branch key to your project.

After you register your app, your Branch key can be retrieved on the Settings page of the dashboard. Add it (them, if you want to do it for both your live and test apps) to your project's manifest file as a meta data.

Edit your manifest file to have the above items

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="io.branch.sample"
    android:versionCode="1"
    android:versionName="1.0" >

    <uses-permission android:name="android.permission.INTERNET" />

    <application>
        <!-- Other existing entries -->

        <!-- Add this meta-data below, and change "key_live_xxxxxxx" to your actual live Branch key -->
        <meta-data android:name="io.branch.sdk.BranchKey" android:value="key_live_xxxxxxx" />

        <!-- For your test app, if you have one; Again, use your actual test Branch key -->
        <meta-data android:name="io.branch.sdk.BranchKey.test" android:value="key_test_yyyyyyy" />
    </application>
</manifest>

Proguard settings for leveraging Branch's pooled matching

To collect the Google Advertising ID, you must ensure that proguard doesn't remove the necessary Google Ads class. The surest way to do this is add it to your proguard rules. If your Application is enabled with proguard, add the following instruction to your proguard.cfg or proguard-rules.pro file:

-keep class com.google.android.gms.** { *; }

In case you are using Facebook SDK to support deep linking through Facebook ads, please make sure to keep the Facebook SDK classes in proguard

-keep class com.facebook.applinks.** { *; }
-keepclassmembers class com.facebook.applinks.** { *; }
-keep class com.facebook.FacebookSdk { *; }

If you are adding support for Huawei devices without Google Mobile Services, please make sure to add this to your proguard rules.

-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

Instant App Deep Linking and Attribution Support

The Branch SDK make it easier to deep link and attribute your Instant Apps. Since Branch automatically configures and hosts the assetlinks.json file for you, you don't need to worry about all the complexity involved in setting up Android App Links. Additionally, the Branch SDK makes it easy to deferred deep link from the Instant App through the full Android app install, providing attribution for every step of the way. Please make sure you have the following added along with regular Branch implementation for instant app enabled project

You can check out a full demo application on our Github. We've replicated our original Android demo application and modified it to support Android Instant Apps.

1. Initialize the Branch SDK

Head to your core library project, where your Application class is defined and drop in the snippet of code to the onCreate() method as follows.

public void onCreate() {
  super.onCreate();

  // Initialize the Branch SDK
  Branch.getAutoInstance(this);
}

2. Add your Branch keys

Instant Apps can be rather confusing as there are many different manifests, but you want to find the Manifest that contains your application tags. Make sure your Application class name is defined here, and then specify the Branch keys inside the application element.

<application
        android:allowBackup="true"
        android:label="@string/app_name"
        android:theme="@style/AppTheme"
        android:supportsRtl="true"
        android:name=".MyApplication">

  <meta-data android:name="io.branch.sdk.TestMode" android:value="false" /> <!-- Set to true to use Branch_Test_Key -->
  <meta-data android:name="io.branch.sdk.BranchKey" android:value="key_live_my_live_key" />
  <meta-data android:name="io.branch.sdk.BranchKey.test" android:value="key_test_my_test_key" />
</application>

3. Configure your Branch links as Android App Links

This guide presumes that you've already configured Branch for Android App Links in the past. If you haven't configured your full native app to use Branch as Android App Links, please complete this guide which will correctly configure the dashboard and manifest.

Now, you simply need to edit the above manifest and paste in the following snippet inside the application element. Then you'll need to replace the xxxx with your own custom subdomain which will be visible on the Branch link settings dashboard at the bottom of the page. If you're using a custom subdomain, you can find the advanced instructions in the above link regarding configuring Android App Links.

<application
  ......

  <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https" android:host="xxxx.app.link" />
      <data android:scheme="https" android:host="xxxx-alternate.app.link" />
  </intent-filter>

</application>

4. Retrieve Branch deep link data

Now that you've outfitted your Instant App project with the above, you can now register a deep link router function for activities you want to receive the deep link data in any Activity split, similar to how you would retrieve deep link data in the full app.

5. Configure the deep linking from Instant App to your Full App

Now, the user has arrived in your Instant App and you're ready to convert them to install your full native app. Don't worry, Branch as got your covered! We have overridden the default showInstallPrompt with a method that auto configures the Google Play prompt with all of the deep link data you need to carry context through install. Additionally, we can provide you the full set of attribution on how many users conver through this prompt.

Branch SDK provides convenient methods to check for app types and full app conversion. This eliminates the dependency on Google IA support SDK ('com.google.android.instantapp'). Here are some of the methods that makes life easy

• Branch#isInstantApp()

This convenience methods checks whether the current version of app running is Instant App or Full Android App to allow you convenience

• Branch#showInstallPrompt()

This methods shows an install prompt for the full Android app, allowing you an easy way to pass Branch referring deep data to the full app through the install process. Similar to how deferred deep linking works for Branch normally, the full app will receive the deep link params in the handle callback.

The below example shows how to create a custom Branch Universal Object, the associate it with the installation prompt that will be passed through to your full native Android app after the user installs.

if (Branch.isInstantApp(this)) {
  myFullAppInstallButton.setVisibility(View.VISIBLE);
  myFullAppInstallButton.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
       BranchUniversalObject branchUniversalObject = new BranchUniversalObject()
           .setCanonicalIdentifier("item/12345")
           .setTitle("My Content Title")
           .setContentDescription("My Content Description")
           .setContentImageUrl("https://example.com/mycontent-12345.png")
           .setContentMetadata(new ContentMetadata()
                 .addCustomMetadata("property1", "blue")
                 .addCustomMetadata("property2", "red"));

      Branch.showInstallPrompt(myActivity, activity_ret_code, branchUniversalObject);
    }
  });
} else {
  myFullAppInstallButton.setVisibility(View.GONE);
}

Initialization

If your minimum sdk level is 15+, To receive the deep link parameters from the Branch SDK, call initSession and pass in the BranchReferralInitListener. This will return the dictionary of referringParams associated with the link that was just clicked. You can call this anywhere at any time to get the params.

If you need to support pre 15, Branch must know when the app opens or closes to properly handle the deep link parameters retrieval. You can see more details on how to do this at [this docs site](/developers-hub/docs/android-sdk-overview. Basically, if you don't close the Branch session, you'll see strange behaviors like deep link parameters not showing up after clicking a link the second time.

Initialize Branch lifecycle

Initialising and closing session is done automatically with our new automatic session management.

Alt 1: You Have A Custom Application Class

If you have a custom Application class, just add this call in onCreate

public void onCreate() {
    super.onCreate();
    Branch.getAutoInstance(this);
}

Alt 2: You Don't Have A Custom Application Class

If you are not creating or using an Application class throughout your project, all you need to do is declare BranchApp as your application class in your manifest.

<application
    android:name="io.branch.referral.BranchApp">

Register deep link router

// Listener (within Main Activity's onStart)
Branch.sessionBuilder(this).withCallback(new Branch.BranchReferralInitListener() {
	@Override
	public void onInitFinished(JSONObject referringParams, BranchError error) {
		if (error == null) {
			Log.i("BRANCH SDK", referringParams.toString());
		} else {
			Log.i("BRANCH SDK", error.getMessage());
		}
	}
}).withData(this.getIntent().getData()).init();

// Latest
JSONObject sessionParams = Branch.getInstance().getLatestReferringParams();

// First
JSONObject installParams = Branch.getInstance().getFirstReferringParams();

// Listener (within Main Activity's onStart)
    Branch.sessionBuilder(this).withCallback(object : BranchReferralInitListener {
        override fun onInitFinished(referringParams: JSONObject?, error: BranchError?) {
            if (error == null) {
                Log.i("BRANCH SDK", referringParams.toString())
            } else {
                Log.e("BRANCH SDK", error.message)
            }
        }
    }).withData(this.intent.data).init()

    // Latest
    val sessionParams = Branch.getInstance().latestReferringParams

    // First
    val installParams = Branch.getInstance().firstReferringParams

📘

Note

If you're calling this inside a fragment, please use getActivity() instead of passing in this. Also, this.getIntent().getData() refers to the data associated with an incoming intent.

Next, you'll need to hook into the onNewIntent method specified inside the Activity lifecycle and set the intent. This is required for conformity with Facebook's AppLinks. Verify that the activity you're implementing has launchMode set to singleTask inside the Manifest declaration. Once that is done, go to said activity and do something like the following:

@Override
public void onNewIntent(Intent intent) {
    this.setIntent(intent);
}

Branch-provided data parameters in sessionBuilder.init() callback

Previously, Branch did not return any information to the app if sessionBuilder.init() was called but the user hadn't clicked on a link. Now Branch returns explicit parameters every time. Here is a list, and a description of what each represents.

• ~ denotes analytics
• + denotes information added by Branch
• (for the curious, $ denotes reserved keywords used for controlling how the Branch service behaves)

Retrieve session (install or open) parameters

These session parameters will be available at any point later on with this command. If no params, the dictionary will be empty. This refreshes with every new session (app installs AND app opens)

Branch branch = Branch.getInstance(getApplicationContext());
JSONObject sessionParams = branch.getLatestReferringParams();

To retrieve this information synchronously, call the following from a non-UI thread:

JSONObject sessionParams = branch.getLatestReferringParamsSync();

Retrieve install (install only) parameters

If you ever want to access the original session params (the parameters passed in for the first install event only), you can use this line. This is useful if you only want to reward users who newly installed the app from a referral link or something.

Branch branch = Branch.getInstance(getApplicationContext());
JSONObject installParams = branch.getFirstReferringParams();

To retrieve this information synchronously, call the following from a non-UI thread:

JSONObject sessionParams = branch.getFirstReferringParamsSync();

Persistent identities

Often, you might have your own user IDs, or want referral and event data to persist across platforms or uninstall/reinstall. It's helpful if you know your users access your service from different devices. This where we introduce the concept of an 'identity'.

To identify a user, just call:

Branch branch = Branch.getInstance(getApplicationContext());
branch.setIdentity(your user id); // your user id should not exceed 127 characters

Logout

If you provide a logout function in your app, be sure to clear the user when the logout completes. This will ensure that all the stored parameters get cleared and all events are properly attributed to the right identity.

🚧

Warning

This call will clear the referral credits and attribution on the device.

Branch.getInstance(getApplicationContext()).logout();

Branch Universal Objects

The Branch Android SDK uses the concept of a Branch Universal Object (BUO) to represent the thing you want to share. A BranchUniversalObject instance encapsulates a unique piece of content, such as an article, video, or item for sale.

You can set all the metadata associated with the object, then call action methods on it to do things like get a link or register a view.

Learn more about creating BUOs to utilize deep linking, sharing content, content analytics, content indexing, and event tracking.

Track User Actions and Events

The BranchEvent class is used to make a Branch Event out of an event or action that has taken place in your app. Examples include tracking when a user adds an item to an online shopping cart or searches for a keyword.

You can associate a BUO with a Branch Event by adding the BUO instance to the Branch Event's contentItems field.

You can also view analytics for your Branch Events on the Branch dashboard. Branch Events seamlessly integrate with many third party analytics providers like Google Analytics and Criteo.

Learn more about the different classes of Branch Events, including the Custom class for tracking events that aren't predefined.

Register User Actions On An Object

This functionality is deprecated. Please consider using BranchEvent for tracking user action and events as described here.

We've added a series of custom events that you'll want to start tracking for rich analytics and targeting. Here's a list below with a sample snippet that calls the register view event.

Creating a Deep Link

Once you've created your Branch Universal Object, which is the reference to the content you're interested in, you can then get a link back to it with the mechanisms described below. First define the properties of the link itself.

LinkProperties linkProperties = new LinkProperties()
               .setChannel("facebook")
               .setFeature("sharing")
               .addControlParameter("$desktop_url", "https://example.com/home")
               .addControlParameter("$ios_url", "https://example.com/ios");

You do custom redirection by inserting the following optional keys in the control params:

You have the ability to control the direct deep linking of each link by inserting the following optional keys in the control params:

Then, make a request to the Universal Object in order to create the URL.

branchUniversalObject.generateShortUrl(this, linkProperties, new BranchLinkCreateListener() {
    @Override
    public void onLinkCreate(String url, BranchError error) {
        if (error == null) {
            Log.i("MyApp", "got my Branch link to share: " + url);
        }
    }
});

Showing a Custom Share Sheet

We’ve realized that Android had some very poor offerings for native share sheet functionality, so we built our own and bundled it into the core SDK. This share sheet it customizable and will automatically generate a link when the user selects a channel to share to.

To use it, first define the custom share sheet style like so. Most of these are completely optional and we've got a great set of defaults if you don't want to spend hours customizing.

ShareSheetStyle shareSheetStyle = new ShareSheetStyle(MainActivity.this, "Check this out!", "This stuff is awesome: ")
                .setCopyUrlStyle(getResources().getDrawable(android.R.drawable.ic_menu_send), "Copy", "Added to clipboard")
                .setMoreOptionStyle(getResources().getDrawable(android.R.drawable.ic_menu_search), "Show more")
                .addPreferredSharingOption(SharingHelper.SHARE_WITH.FACEBOOK)
                .addPreferredSharingOption(SharingHelper.SHARE_WITH.EMAIL)
                .setAsFullWidthStyle(true)
                .setSharingTitle("Share With");

To show the share sheet, call the following on your Branch Universal Object. There are plenty of callback methods for you to hook into as you need for your own customizations on top of our animation.

branchUniversalObject.showShareSheet(this,
                                      linkProperties,
                                      shareSheetStyle,
                                       new Branch.ExtendedBranchLinkShareListener() {
    @Override
    public void onShareLinkDialogLaunched() {
    }
    @Override
    public void onShareLinkDialogDismissed() {
    }
    @Override
    public void onLinkShareResponse(String sharedLink, String sharedChannel, BranchError error) {
    }
    @Override
    public void onChannelSelected(String channelName) {
    }
    @Override
    public boolean onChannelSelected(String channelName, BranchUniversalObject buo, LinkProperties linkProperties) {
        return false;
    }
});

Enable or Disable User Tracking

In order to comply with tracking requirements, you can disable tracking at the SDK level. Simply call:

Branch.getInstance().disableTracking(true);

This will prevent any Branch requests from being sent across the network, except for the case of deep linking. If someone clicks a Branch link, but has expressed not to be tracked, we will return deep linking data back to the client but without tracking information captured.

In do-not-track mode, you will still be able to create and share links. They will not have identifiable information. Event tracking won’t pass data back to the server if a user has expressed to not be tracked. You can change this behavior at any time, but calling the above function. This information will be saved and persisted.

Control How Branch Handles Network Requests

By default, Branch Android SDK uses Java's javax.net.ssl.HttpsURLConnection for network requests. There are known issues with that interface and typically applications use third party networking libraries, such as OkHttp, to customize their networking. Branch SDK provides an interface, BranchRemoteInterface, to apply your networking customization to how Branch handles network requests. Use the below API to set your implementation of BranchRemoteInterface to handle Branch requests.

setBranchRemoteInterface(@NonNull BranchRemoteInterface remoteInterface)

setBranchRemoteInterface(remoteInterface: BranchRemoteInterface)

Below is an example of an implementation of BranchRemoteInterface using OkHttp.

public class OkhttpBranchNetworkInterface extends BranchRemoteInterface {
  private OkHttpClient okHttpClient = new OkHttpClient.Builder().readTimeout(3, TimeUnit.SECONDS).writeTimeout(3, TimeUnit.SECONDS).connectTimeout(3, TimeUnit.SECONDS).build();

  @Override
  public BranchResponse doRestfulGet(String url) throws BranchRemoteException {
    Request request = new Request.Builder().url(url).build();

    return handleNetworkRequest(request);
  }

  @Override
  public BranchResponse doRestfulPost(String url, JSONObject payload) throws BranchRemoteException {
    Request request = new Request.Builder().url(url).post(RequestBody.create(MediaType.parse("application/json"), payload.toString())).build();

    return handleNetworkRequest(request);
  }

  private BranchResponse handleNetworkRequest(Request request) throws BranchRemoteException {
    try {
      Response response = okHttpClient.newCall(request).execute();
      ResponseBody rb = response.body();
      if (rb != null) throw new BranchRemoteException(BranchError.ERR_BRANCH_NO_CONNECTIVITY);
      return new BranchResponse(rb.string(), response.code());
    } catch(Exception exception) {
      if (exception instanceof SocketTimeoutException) {
        // add desired retry logic, then eventually throw BranchError.ERR_BRANCH_REQ_TIMED_OUT
        throw new BranchRemoteException(BranchError.ERR_BRANCH_REQ_TIMED_OUT);
      } else {
        // handle other failures as needed, throw BranchError.ERR_BRANCH_NO_CONNECTIVITY as a default
        throw new BranchRemoteException(BranchError.ERR_BRANCH_NO_CONNECTIVITY);
      }
    }
  }
}

public class OkhttpBranchNetworkInterface extends BranchRemoteInterface {
  private OkHttpClient okHttpClient = new OkHttpClient.Builder().readTimeout(3, TimeUnit.SECONDS).writeTimeout(3, TimeUnit.SECONDS).connectTimeout(3, TimeUnit.SECONDS).build();

  @Override
  public BranchResponse doRestfulGet(String url) throws BranchRemoteException {
    Request request = new Request.Builder().url(url).build();

    return handleNetworkRequest(request);
  }

  @Override
  public BranchResponse doRestfulPost(String url, JSONObject payload) throws BranchRemoteException {
    Request request = new Request.Builder().url(url).post(RequestBody.create(MediaType.parse("application/json"), payload.toString())).build();

    return handleNetworkRequest(request);
  }

  private BranchResponse handleNetworkRequest(Request request) throws BranchRemoteException {
    try {
      Response response = okHttpClient.newCall(request).execute();
      ResponseBody rb = response.body();
      if (rb != null) throw new BranchRemoteException(BranchError.ERR_BRANCH_NO_CONNECTIVITY);
      return new BranchResponse(rb.string(), response.code());
    } catch(Exception exception) {
      if (exception instanceof SocketTimeoutException) {
        // add desired retry logic, then eventually throw BranchError.ERR_BRANCH_REQ_TIMED_OUT
        throw new BranchRemoteException(BranchError.ERR_BRANCH_REQ_TIMED_OUT);
      } else {
        // handle other failures as needed, throw BranchError.ERR_BRANCH_NO_CONNECTIVITY as a default
        throw new BranchRemoteException(BranchError.ERR_BRANCH_NO_CONNECTIVITY);
      }
    }
  }
}