1. SDK Integration Guide

Contents

  1. Get the SDK files
  2. Enable Branch on mParticle
  3. Configure Manifest
  4. Start a Branch session
  5. Handle Incoming Links
  6. Recommended: Track in-app events
  7. Next steps
Prerequisites

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

Prerequisites

Before enabling the Branch SDK on mParticle, you must first sign up for an mParticle account and complete the setup and integration process.

linkGet the SDK files

With extensive use, the Android SDK footprint is 187 kb.

linkInstall with Gradle

Add compile 'com.mparticle:android-branch-kit:4.+' to the dependencies section of your build.gradle file.

linkEnable Branch on mParticle

  1. Retrieve your Branch Key on the Settings page of the Branch dashboard.
  2. From your mParticle dashboard navigate to the Services page. (The paper airplane icon on the left side)
  3. Scroll down to the Branch tile, or enter Branch in the search bar.
  4. Click on the Branch tile and then select “Activate a Platform”.
  5. Click on the Android icon, then toggle the status ON.
  6. Enter your Branch key in the marked field and click “Save”.

linkConfigure Manifest

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

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:

<activity
    android:name="com.yourapp.SplashActivity"
    android:label="@string/app_name"
    android:launchMode="singleTask">

linkStart a Branch session

As with any kit, mParticle will automatically handle initializing Branch sessions. At this point you should start seeing your Branch session data - including installs, re-opens, and any custom events - in your Branch dashboard.

linkHandle Incoming Links

Open the Activity for which you registered the Intent in the previous section, and hook into the onStart lifecycle method by adding this override:

@Override
public void onStart() {
  MParticle.getInstance().checkForDeepLink(new DeepLinkListener() {
    @Override
    public void onResult(DeepLinkResult result) {
        // Check for the existence of a given key in the link data and route accordingly.
        try {
            if ((result.getParameters().has("my_custom_key")) && (result.getParameters().get("my_custom_key").equals("custom value"))) {
                // Send user to intended path
            }
        } catch (JSONException e) {

        }
    }

    @Override
    public void onError(DeepLinkError error) {
        // If an error occurred, it will be surfaced via a DeepLinkError.
        Log.d("my log tag", error.toString());
    }
  });
}

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.

Every custom event that you track with mParticle will be automatically forwarded to Branch.

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