Branch Discovery SDK

The Branch Discovery SDK is an Android SDK provided by Branch to power in-app search on Android devices. This SDK is a thin wrapper with helper classes to assist in building search user experiences on top of the Branch Discovery API. This SDK and API allow your users to search through the tens of billions of deep links to app pages that Branch has indexed from its core linking platform used by tens of thousands of mobile applications.

Getting Started

Installation

The compiled Branch Discovery SDK footprint is approximately 40kb

Install Branch Discovery SDK

Add implementation 'io.branch.sdk.android:search:1.x.y' to the dependencies section of your build.gradle file, where x and y correspond to the latest release version.

Additional dependencies and permissions

Permissions

1. Internet access permissions are required in order to request and return search results as you would expect
2. (optional, but strongly recommended) Location permission. When enabled, location will greatly enhance search results and is required in order to display local results. If your project does not already use location services, you will need to add the following to your build.gradle dependency list:

    implementation 'com.google.android.gms:play-services-location:' + PLAY_SERVICE_VERSION

3. (mandatory) Google Play services to access advertising IDs. This lets Branch use its network of app usage information to personalize and improve the user experience. To support this, make sure the following is in your build.gradle dependency list:

    implementation 'com.google.android.gms:play-services-ads:' + PLAY_SERVICE_VERSION

4. (mandatory) Add okhttp library to handle network requests

    implementation 'com.squareup.okhttp3:okhttp:3.12.6'

Register Your App

You will need to sign up here to request a a [Branch Discovery API Key] (https://branch.io/discovery-signup/).

Add your Branch key to your project.

Once you receive your Branch Discovery API Key, edit your app's manifest file to include the following:

<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" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

    <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" />
    </application>
</manifest>

Integrating Branch Discovery SDK

Initialization

The Branch Discovery SDK needs to be initialized before using any search functionality. The SDK can be initialized anywhere within your application. Ideally should be from the onCreate() method of the application class. Alternatively it can be initialized from the onCreate() method of the Activity, however subsequent calls to init() will not reinitialize the SDK.

BranchSearch.init(getApplicationContext());

Hints

To educate your users on the value of in-app search, this endpoint will return you a short list of query "hints" that you can suggest to the user to try, even before they've began to type a search query. These are trending queries from a range of content verticals.

BranchQueryHintRequest request = BranchQueryHintRequest.create();
BranchSearch.getInstance().queryHint(request, new IBranchQueryHintEvents() {

    @Override
    public void onBranchQueryHintResult(@NonNull BranchQueryHintResult result) {
        Log.d("Branch", "QueryHint results: " + result.getHints().toString());
        queryHints = result.getHints();
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                updateQueryHint();
            }
        });
    }

    @Override
    public void onBranchQueryHintError(@NonNull BranchSearchError error) {
        if (error.getErrorCode() == BranchSearchError.ERR_CODE.REQUEST_CANCELED) {
            Log.d(TAG, "Branch QueryHint request was canceled.");
        } else {
            // Handle any errors here
            Log.d(TAG, "Error for Branch QueryHint. " +
                    error.getErrorCode() + " " + error.getErrorMsg());
        }
    }
});

When hints are clicked

When a BranchQueryHint object is clicked by the user, you can create a search request by passing the hint to BranchSearchRequest.create(BranchQueryHint), or simply use branchQueryHint.toSearchRequest(). This gives better analytics to Branch and let us improving the service.

BranchQueryHint clickedHint = ...;
BranchSearchRequest request = clickedHint.toSearchRequest();
BranchSearch.getInstance().query(request, ...);

The triggered search request can also be created by passing a String, in which case you should make sure to call BranchSearchRequest.setQuerySource(BranchQuerySource.QUERY_HINT_RESULTS).

Auto Suggest

As a user is typing, Auto Suggest (sometimes referred to as autocomplete) will return a list of query completions that reflet our best predictions for what the user is searching for. We strongly recommend you add Auto Suggest to your UI since it is a critical element of a modern search experience that users now expect.

BranchAutoSuggestRequest request = BranchAutoSuggestRequest.create("pizza");
BranchSearch.getInstance().autoSuggest(request, new IBranchAutoSuggestEvents() {
    @Override
    public void onBranchAutoSuggestResult(@NonNull BranchAutoSuggestResult result) {
        Log.d("Branch", "onAutoSuggest: " + result.getSuggestions().toString());
    }

    @Override
    public void onBranchAutoSuggestError(@NonNull BranchSearchError error) {
        if (error.getErrorCode() == BranchSearchError.ERR_CODE.REQUEST_CANCELED) {
            Log.d(TAG, "Branch AutoSuggest request was canceled.");
        } else {
            // Handle any errors here
            Log.d(TAG, "Error for Branch AutoSuggest. " +
                    error.getErrorCode() + " " + error.getErrorMsg());
        }
    }
});

When suggestions are clicked

When a BranchAutoSuggestion object is clicked by the user, you can create a search request by passing the hint to BranchSearchRequest.create(BranchAutoSuggestion), or simply use branchAutoSuggestion.toSearchRequest(). This gives better analytics to Branch and let us improving the service.

BranchAutoSuggestion clickedSuggestion = ...;
BranchSearchRequest request = clickedSuggestion.toSearchRequest();
BranchSearch.getInstance().query(request, ...);

The triggered search request can also be created by passing a String, in which case you should make sure to call BranchSearchRequest.setQuerySource(BranchQuerySource.AUTOSUGGEST_RESULTS).

Search for In-App Content

When a user begins typing into your search box, you should create a BranchSearchRequest to search for apps and content with Branch. Create a builder for each phrase you would like to search for. Don't worry, we handle debounce so feel free to create one with every character entered.

Note that the Branch Discovery SDK will provide better results if it can use the current location. For example, a user searching for a restaurant will receive location specific results if location permissions are enabled. Be sure to pass the user location to BranchSearch.getInstance().setLocation()! For your reference, in io.branch.search.demo.util.BranchLocationFinder, we have provided example code that fetches the device's last known location.

// Create a Branch Search Request for the keyword
// Implementation Note:  Set the last known location before searching.
BranchSearchRequest request = BranchSearchRequest.create(keyword);

// Search for the keyword with the Branch Search SDK
BranchSearch.getInstance().query(request, new IBranchSearchEvents() {
    @Override
    public void onBranchSearchResult(@NonNull BranchSearchResult branchSearchResult) {
        // Update UI with search results. BranchSearchResult contains the result of any search.
        branchSearchController.onBranchSearchResult(branchSearchResult);
    }

    @Override
    public void onBranchSearchError(@NonNull BranchSearchError error) {
        // Handle any search errors here
    }
});

Controlling numbers of results

BranchSearchRequest is a builder and allows other attributes to be added to the query, such as limiting number of results per app or maximum number of results. Search results are always updated through the onBranchSearchResult(BranchSearchResult branchSearchResult) callback.

Maximum app results

You can control the maximum number of distinct app groups (see format of results in next section) that are returned by the API using the following code. The default is 5.

    BranchSearchRequest.create(search_phrase)
      .setMaxAppResults(10)

Maximum content per app

You can control the maximum number of content links that are returned per app (see format of results in next section) that are returned by the API using the following code. The default is 5.

    BranchSearchRequest.create(search_phrase)
      .setMaxContentPerAppResults(10)

Displaying the search results from BranchSearchRequest

The structure of the results in the query are as follows, and are intended to fit the expected presentation of results. The model is very similar to how Spotlight search results are structured: clustered by app, with a sub list of containing deep links. Here's a model that may be helpful:

`BranchSearchResult`
  [
    `BranchAppResult` 
      [ 
        `BranchLinkResult`, 
        `BranchLinkResult`, 
        `BranchLinkResult`,
        ... 
      ],
    `BranchAppResult` 
      [ 
        `BranchLinkResult`, 
        `BranchLinkResult`, 
        `BranchLinkResult`,
        ... 
      ],
    ...
  ]

BranchSearchResult Class

The BranchSearchResult object is returned to you from a successful query and contains some information relevant for processing search results. The object has the following important properties:

BranchAppResult class

Branch will return to you a list of relevants apps for each query, similar to if the user were searching on-device or via the Play Store. The app results are returned in the appResults list in the BranchSearchResult object. A few key parameters of this object are:

BranchLinkResult class

Branch will also return relevant content to the user query. These are deep links to pages inside of apps, ranked in a personal way for the user. Note that we will also return content for apps that are not installed. In the case that the app is not installed, we will route the user to the web page version of the content if available. Not all applications have websites though.

Handling errors with BranchSearchError

The only thing consistent when working in mobile is that the network can fail regularly. Plus, there are all sorts of other reasons your search request might fail. Inevitably, you'll need to handle the variety of reasons why the request might fail, and we started to accumulate some of the common ones we see.

BranchSearchError class

Here are the possible methods to use on the error object:

And here are the actual codes and corresponding root causes:

Special Shortcut Handling (for non-Launchers)

This section only applies to Android clients that are not Launchers

Some shortcut links returned by Branch can only be opened by a launcher. To open such links, the Branch Discovery SDK utilizes a permission for interacting with the LauncherApps Service that Android grants the default launcher. If the SDK determines that it does not have this permission, it will not include these shortcut links in the search results. If your client has alternate access to the LauncherApps Service, you may override how the SDK handles these shortcut links.

IBranchShortcutHandler Interface

Branch provides an easy way to override how the SDK accesses the LauncherApps Service via the io.branch.search.IBranchShortcutHandler interface. You can create a class that implements this interface and set your class as the shortcut handler via setShortcutHandler method in your BranchConfiguration. The IBranchShortcutHandler interface has 2 methods you will implement: