Android SDK

Important: Minimum supported system WebView version for surveys is 51.0.2704.90, it is default for Android 7.0.

LATEST Android SDK Version: 1.0.20

Setup#

Integration is easiest with gradle dependency. In order to do that you need to add two pieces of code to your project. First goes into root build.gradle file. You need to add jitpack.io repository into list of repositories for all projects like this:

allprojects {
    repositories {
        // other repositories here
        maven { url 'https://jitpack.io' }
    }
}

After that you just need to add the actual SDK dependency into build.gradle of the app module:

dependencies {  
    // other dependencies here
    implementation 'com.github.inbrainai:sdk-android:1.0.20'  
}

After re-syncing the project from gradle files you will be able to start using inBrain SDK.

Configuration#

InBrain SDK configuration can be completed at app launch or before SDK usage. Follow the steps below as our recommendation for properly configuring the InBrain SDK before use:

1.) Use the following to pass your API keys and a unique User_Id. See our Getting Started guide to generating your ClientId and Secret Key. Also note that by default you should pass true for isS2S by default.

InBrain.getInstance().setInBrain(this, API_CLIENT_ID, API_SECRET, isS2S, USER_ID);

2.) To subscribe to events, add the following. Event callbacks are covered more in detail here.

InBrain.getInstance().addCallback(callback);

3.) Customize the UI. Below is example code and more detail on UI customization is discussed here

ToolBarConfig toolBarConfig = new ToolBarConfig();
toolBarConfig.setTitle(getString(R.string.app_name)); // set title

boolean useResourceId = false;
if (useResourceId) {
    toolBarConfig.setToolbarColorResId(R.color.colorAccent) // set toolbar color with status bar
            .setBackButtonColorResId(android.R.color.white) // set icon color
            .setTitleColorResId(android.R.color.white); //  set toolbar text
} else {
    toolBarConfig.setToolbarColor(getResources().getColor(R.color.colorAccent))
            .setBackButtonColor(getResources().getColor(android.R.color.white))
            .setTitleColor(getResources().getColor(android.R.color.white));
}
toolBarConfig.setElevationEnabled(false);
InBrain.getInstance().setToolbarConfig(toolBarConfig);

StatusBarConfig statusBarConfig = new StatusBarConfig();
if (useResourceId) {
    statusBarConfig.setStatusBarColorResId(android.R.color.white)
            .setStatusBarIconsLight(false);
} else {
    statusBarConfig.setStatusBarColor(getResources().getColor(android.R.color.white))
            .setStatusBarIconsLight(false);
}
InBrain.getInstance().setStatusBarConfig(statusBarConfig);

Usage#

inBrain offers two methods of displaying surveys to your users. The simplest method is use of the inBrain Survey Wall, which presents the inBrain experience with no additional work required. See the this section

A second method is use of the inBrain Native Surveys, which acts as an API to fetch surveys and leaves the display of those surveys up to you. It's explained in detail here

Survey Wall#

In order to open inBrain survey wall, execute the following call:

InBrain.getInstance().showSurveys(activity, new StartSurveysCallback() {
    @Override
    public void onSuccess() {
        // inBrain is successfully started
    }

    @Override
    public void onFail(String message) {
        // failed to start inBrain
    }
});

This will open the survey wall in new activity. inBrain SDK will handle everything else. It will return control to last opened activity of your app after user leaves the survey wall. More on receiveing those events detailed here

Native surveys#

Native Surveys act as a simple API via the SDK to fetch and display surveys.

1.) Use the following to fetch surveys:

InBrain.getInstance().getNativeSurveys(PLACEMENT_ID, surveyList -> {
            //display surveys to the user
            Log.d("MainActivity", "Count of Native Surveys returned:" + surveyList.size());
        });

3) Next you will display the surveys from step #1 within your app. When the user selects one of these surveys, use the following function to display the survey:

InBrain.getInstance().showNativeSurveyWith(this, surveyId, PLACEMENT_ID, new StartSurveysCallback() {
            @Override
            public void onSuccess() {
                Log.d("MainActivity", "Successfully started InBrain");
            }

            @Override
            public void onFail(String message) {
                Log.e("MainActivity", "Failed to start inBrain:" + message);
            }
        });

Custom Tracking Data & Demographic Data#

The inBrain SDK provides an additional function setInBrainValuesFor() which allows you to do two things:

1.) Provide demographic data to provide an even more seamless on-boarding of your users into the inBrain experience. You can pass gender and age with the following

HashMap<String, String> dataOptions = new HashMap<>();
dataOptions.put("gender", "female");
dataOptions.put("age", "26");
InBrain.getInstance().setInBrainValuesFor(null, dataOptions);

2.) Provide tracking data that can be used internally within your system. The tracking data you supply as SessionId will be provided in the Server to Server Callback inBrain sends to your server.

String trackingData = "{ someCustomField: 'tracking_data'}";
inBrain.setInBrainValuesFor(sessionID: trackingData, null)

Please, note: The above configuration should be done before showing the surveys, or it will have no effect.

Callbacks#

In app callbacks are delegate functions that are executed upon specific events and allow you to intercept those events. Below is an example of setting up event callbacks:

private final InBrainCallback callback = new InBrainCallback() {
        @Override
        public void surveysClosed() {
            Log.d("MainActivity", "Survey Wall Closed");
            // User Closed The Survey Wall and Control returned to App
            // Get Rewards earned from Survey Wall Flow
            getInBrainRewards();
        }

        @Override
        public void surveysClosedFromPage() {
            Log.d("MainActivity", "Native Survey Closed");
            // Native Survey Flow Finished and Control returned to App
            // Get Rewards earned from Native Survey Flow
            getInBrainRewards();
        }

        @Override
        public boolean didReceiveInBrainRewards(List<Reward> rewards) {
            // THIS METHOD IS DEPRECATED...USE getInBrainRewards() INSTEAD
            // note: this method can be called during SDK usage while your activity is in 'onStop' state
            return false; //this should always be false
        }
    };

If you added a callback in onCreate, you should remove you callback in onDestroy method of an activity like this:

    @Override
    protected void onDestroy() {
        InBrain.getInstance().removeCallback(callback); // unsubscribe from events
        super.onDestroy();
    }

Don't forget to remove the callbacks, otherwise it can cause a memory leak!

Check For Rewards in App#

The typical inBrain integration flow is that your app would receive reward events to your server via Server-to-Server callbacks as opposed to checking for earned rewards within the app experience. In the case that you DO want to check for rewards earned during the inBrain experience, you can utilize the following:

InBrain.getInstance().getRewards(new GetRewardsCallback() {  
    @Override  
    public boolean handleRewards(List<Reward> rewards) {  
        // Process rewards, display to users, etc.
        return true; // must return true! failure to return true may result in receiving duplicate rewards within this function
    }  
  
    @Override  
    public void onFailToLoadRewards(Throwable t) {  
        // Handle the fail, where t is an throwable that might help to investigate the error.
    }  
});

*Note: We highly recommend using Server-to-Server Callbacks for receiving and processing rewards.

Custom UI Configuration#

1. Toolbar:

ToolBarConfig toolBarConfig = new ToolBarConfig();

Set toolbar color:

toolBarConfig.setToolbarColor(getResources().getColor(R.color.your_color));

Also you may pass color's resource id:

toolBarConfig.setToolbarColorResId(R.color.your_color);

Title:

toolBarConfig.setToolbarTitle(getString(R.string.app_name));

If you want to leave toolbar's text empty, just pass empty String to it.

toolBarConfig.setToolbarTitle("");

Title text's color:

toolBarConfig.setTitleColor(getResources().getColor(R.color.your_color));

Also you may pass color's resource id:

toolBarConfig.setTitleColorResId(R.color.your_color);

Back icon's color:

toolBarConfig.setBackButtonColor(getResources().getColor(R.color.your_color));

Also you may pass color's resource id:

toolBarConfig.setBackButtonColorResId(R.color.your_color);

If you want to enable elevation for toolbar, use:

toolBarConfig.setElevationEnabled(true);

Finally, set toolBarConfig to inBrain:

InBrain.getInstance().setToolbarConfig(toolBarConfig);

2. Status bar:

StatusBarConfig statusBarConfig = new StatusBarConfig();

Set status bar color:

statusBarConfig.setStatusBarColor(getResources().getColor(R.color.your_color));

Also you may pass color's resource id:

statusBarConfig.setStatusBarColorResId(R.color.your_color);

By default, status bar icons' color will be white. If you need to use black status bar icons:

statusBarConfig.setStatusBarIconsLight(false);

Supported Country Language List#

By default, the device locale language will be used. This controls which language the inBrain experience will be presented with as well as surveys for that specific country/language locale

Accepted languages: "de-de", "en-au", "en-ca", "en-gb", "en-in", "en-us", "es-es", "es-mx", "es-us", "fr-ca", fr-fr", "fr-br"

Check if Surveys Available#

The inBrain SDK provides functionality to check if surveys are available for a user. You check for surveys available after the initial inBrain configuration.

InBrain.getInstance().areSurveysAvailable(this, new SurveysAvailableCallback() {
    @Override
    public void onSurveysAvailable(final boolean available) {
        Log.d("MainActivity", "Surveys available:" + available);
    }
});

CHANGELOG