Android SDK

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

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:2.2.0'
}

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

Configuration

The 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(context, API_CLIENT_ID, API_SECRET, isS2S, USER_ID);

2) To subscribe to events, add the following. Event callbacks are covered more in details 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

The 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 this section.

Another 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 details here.

Survey Wall

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

InBrain.getInstance().showSurveys(context, new StartSurveysCallback() {
    @Override
    public void onSuccess() {
        // successfully opened the survey wall
    }

    @Override
    public void onFail(String message) {
        // failed to open the survey wall
    }
});

This will open the survey wall in a new activity. The 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 receiving those events detailed here.

Native surveys

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

Fetch native surveys

1) Use the following to fetch surveys simply without any filtering:

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

2) You can pass in a SurveyFilter as a parameter to fetch specific surveys as needed:

SurveyFilter filter = new SurveyFilter();
filter.placementId = YOUR_PLACEMENT_ID;
filter.includeCategories = yourIncCategories;
filter.excludeCategories = yourExcCategories;

InBrain.getInstance().getNativeSurveys(filter, surveyList -> {
    nativeSurveys = surveyList;
    Log.d("MainActivity", "Count of Native Surveys returned:" + surveyList.size());
});

You may apply different filters at the same time, and all these fields (placementId, includeCategories, excludeCategories) of the SurveyFilter are optional.

Show native surveys

1) Next you will want to display the surveys fetched from Fetch native surveys within your app. When the user selects one of these surveys, use the following to display the survey:

InBrain.getInstance().showNativeSurvey(context, survey, 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);
    }
});

2) You can also pass in some specific surveyId and searchId as function parameters to display the corresponding survey:

InBrain.getInstance().showNativeSurveyWith(context, surveyId, searchId, 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);
    }
});

Understanding Native Surveys

Native Survey is an object which represents survey and has the following properties:

Property	Description
`id`	Id of the survey and the value that should be used when passing parameter to `showNativeSurvey()`
`rank`	A normalized value of 1-N where 1 is highest ranked survey and N is the lowest ranked survey
`time`	An estimation of how many minutes will be required for the user to complete the survey
`value`	Reward the user will earn by completing the survey. This value is in the currency type (points, coins, cents) you specified within the publisher dashboard and already takes into consideration the `revenue share` you've allocated to share with the user for a survey completion.
`isProfilerSurvey`	Boolean value indicating whether the survey represents an inBrain Profiler survey
`currencySale`	Boolean value indicating if the `value` of the survey is adjusted based on an active currency sale
`multiplier`	The currency sale multiplier value applied to the survey `value`
`conversionLevel`	Value that indicates the approximate `conversion` rate of the survey. See possible values here
`categories`	Array of values indicating what categories this survey belongs to. See possible values here
`searchId`	This value should be used when opening a native survey. It includes important encoded information related to placement and category filters

Custom Tracking Data & Demographic Data

The inBrain SDK provides additional functions (setDataOptions(), getDataOptions(), setSessionId(), getSessionId()) which allow you to do two things:

1) Provide demographic data to provide an even more seamless on-boarding of your users into the inBrain experience. For example, 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().setDataOptions(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 the inBrain sends to your server.

String trackingData = "{ someCustomField: 'tracking_data' }";
InBrain.getInstance().setSessionId(trackingData);

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() {
    /**
     Called upon dismissal of inBrainWebView.
     If you are using Native Surveys - please, ensure the surveys reloaded after some survey(s) completed.

     @param byWebView: **true** means closed by WebView's command; **false** - closed by user;
     @param rewards: **NOTE:** At the moment only first** Native Survey reward is delivered.
            That means if the user complete a Native Survey, proceed to Survey Wall and complete one more survey - only first
            reward will be delivered. In case of Survey Wall usage only - no rewards will be delivered.
     */
     
    @Override
    public void surveysClosed(boolean byWebView, List<InBrainSurveyReward> rewards) {
        getInBrainRewards();
    }
};

If you added a callback in onCreate, you should remove your callback in onDestroy method of the 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 the 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);

Check if Surveys are Available

The inBrain SDK provides functionality to check if surveys are available for a user. For best user experience we recommend to check surveys availability prior to call showSurveys(). This should be done after the initial inBrain configuration.

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

Available types and interfaces

Survey Category

The survey may belong to one or a few categories, as well as may have no categories at all. The list of all possible categories may be found bellow:

Automotive
Beverages Alcoholic
Beverages Non Alcoholic
Business
Children & Parenting
Coalition Loyalty Programs
Destinations & Tourism
Education
Electronics, Computer Software
Entertainment And Leisure
Finance, Banking, Investing & Insurance
Food
Gambling, Lottery
Government & Politics
HealthCare
Home
Media & Publishing
Personal Care
Restaurants
Sensitive & Explicit Content
Smoking & Tobacco
Social Research
Sports Recreation Fitness
Telecommunications
Transportation
Travel - Airlines
Travel - Hotels
Travel - Services, Agency, Booking
Credit Cards
Video Games
Fashion & Clothing - Other
Fashion & Clothing - Department Store

Conversion Level

The Conversion Level buckets indicate how the survey has been performing platform-wide at inBrain, not necessarily how well the survey will perform for the user its shown to. Its recommended to use these tags only to portray a unique UI. Possible values are:

New Survey;
Very Poor Conversion
Poor Conversion;
Fair Conversion;
Good Conversion;
Very Good Conversion;
Excellent Conversion.

CHANGELOG

Android SDK

Setup​

Configuration​

Usage

Survey Wall​

Native surveys​

Fetch native surveys​

Show native surveys​

Understanding Native Surveys​

Custom Tracking Data & Demographic Data​

Callbacks​

Check For Rewards in App​

Custom UI Configuration​

Check if Surveys are Available​

Available types and interfaces​

Survey Category​

Conversion Level​

Setup

Configuration

Survey Wall

Native surveys

Fetch native surveys

Show native surveys

Understanding Native Surveys

Custom Tracking Data & Demographic Data

Callbacks

Check For Rewards in App

Custom UI Configuration

Check if Surveys are Available

Available types and interfaces

Survey Category

Conversion Level