CHANGELOG

To check the latest version and all the previous ones of the SDK, you can check this page.

What's new in this page:

Since v3.2.0

• Deprecate Widget types implementation and add a new one.
• Deprecate Leaderboard Widget and add a new one.

Since v3.1.1

• New Widget types
• New Leaderboard Widget

Account Set-Up and retrieving your API Key

Before we can get started with implementing the SDK, you should retrieve your API Key for your integration from the BitLabs Dashboard. If you haven't created an account yet, you can do so here and follow the instructions for the dashboard starting with Sign up & Set up.

Direct download

You can download the BitLabs Android SDK by clicking here.

App-level build.gradle file

Add the following code above the dependencies section of your app-level build.gradle file:

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

repositories {
   maven("https://jitpack.io")
}

Adding Dependencies

dependencies {
   // other dependencies
  
   implementation 'com.github.BitBurst-GmbH.bitlabs-android-library:core:3.1.1'
'

   // other dependencies
}

dependencies {
   // other dependencies

   implementation("com.github.BitBurst-GmbH.bitlabs-android-library:core:3.0.0")

   // other dependencies
}

Allowing your App to access the internet

If your app doesn't have this already, make sure to allow access to the internet.

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

Initialising the SDK

You must initialise the SDK before you can use it. You can do so with the following code.

BitLabs.init(<Context>, "YOUR-TOKEN", "YOUR-USER-ID");

BitLabs.INSTANCE.init(<Context>, "YOUR-TOKEN", "YOUR-USER-ID");

The <Context> is used to get the device Advertising Id to support BitLabs Offers. This is where you will need the API key from the dashboard, as you will need to replace "YOUR-TOKEN" with it. For "YOUR-USER-ID", you will need to dynamically insert the user id for each app user. Make sure the id used here is unique and that it does not change, as the user's profile will be stored under this id.

📘

You can also hold the reference of BitLabs.INSTANCE in a global or local variable like this:

Java

BitLabs bitLabs = BitLabs.INSTANCE

And now you can use the library as

Java

bitLabs.init(<Context>, "YOUR-TOKEN", "YOUR-USER-ID");

Using the SDK

Show the Offer Wall to the user

Now it's time to use the BitLabs SDK so that your users can start taking surveys. Call the .launchOfferWall() function to open the Offer Wall/Direct Link. BitLabs will show up and the user will see qualifications or surveys.

BitLabs.launchOfferWall(<Context>)

BitLabs.INSTANCE.launchOfferWall(<context>)

The <Context> here can be the context of an Activity or of the Application.

👍

That's it!

Theoretically, this is all you have to do. Anything below is optional but can improve the user experience.

Check For Surveys - Check if there's something to do for the user

You can use .checkSurveys(onResponseListener, onErrorListener) to check if a survey is available for the user. The onResponseListener callback will return true whenever there's a survey or a qualification question available for the user. Otherwise, it will return false.

BitLabs.checkSurveys(
  { hasSurveys -> Log.i(<TAG>, if (hasSurveys) "Found Surveys" else "No Surveys") },
  { e -> Log.e(<TAG>, "CheckSurveysErr: ${e.getMessage()}", e.getCause()) }
)

BitLabs.INSTANCE.checkSurveys(
  hasSurveys -> Log.i(TAG, hasSurveys ? "Found Surveys" : "No Surveys"),
  e -> Log.e(TAG, "CheckSurveysErr: " + e.getMessage(), e.getCause())
);

📘

In case an error has occurred, the onError callback will be triggered instead of onResponse. So, make sure to implement it to know what kind of error occurred.

Get Surveys Natively

You can use .getSurveys(onResponseListener, onErrorListener) to get available surveys for the user.

BitLabs.getSurveys(
  { surveys -> Log.i(<TAG>, "Surveys: $surveys") },
  { exception -> Log.e(TAG, "GetSurveysErr: ${exception.getMessage()}", exception.getCause()) }
)

BitLabs.INSTANCE.getSurveys(
  surveys -> Log.i(<TAG>, "Surveys: " + surveys),
  exception -> Log.e(<TAG>, "GetSurveysErr: " + exception.getMessage(), exception.getCause())
);

The onResponseListener callback's parameter is a list of Surveys. A Survey has the following properties:

Native Survey Widgets

getSurveyWidgets (DEPRECATED)

You can use .getSurveyWidgets(<Context>, List<Survey>, WidgetType) to get a RecyclerView of survey widgets.

// If you have a layout, you can add the RecyclerView as shown below
// Note: `this` is the Activity context, and `surveys` is a List<Survey> variable.
layout.addView(bitlabs.getSurveyWidgets(this, surveys, WidgetType.SIMPLE))

// If you have a layout, you can add the RecyclerView as shown below
// Note: `this` is the Activity context, and `surveys` is a List<Survey> variable.
layout.addView(bitlabs.getSurveyWidgets(this, surveys));

The WidgetType can be one of three options:

showSurvey

You can use .showSurvey(<FragmentActivity>, <ContainerResId>, WidgetType) to show the Survey Widget Fragment inside the container provided.

1. FragmentActivity: The Activity where the container exists.
2. ContainerResId: The Resource Id that you added to the container where the Fragment will appear. You have to create this container in your Activity layout to let the SDK know where to render the Widget. It can be a normal View or FragmentContainer
3. WidgetType: The type in which the Survey Widget will appear as. There are three main types for now.

// This usage assumes that the method is being called from within a class 
// that is of/inherits from type FragmentActivity
BitLabs.showSurvey(this, R.id.container_survey_widget, WidgetType.SIMPLE)

// This usage assumes that the method is being called from within a class 
// that is of/inherits from type FragmentActivity
BitLabs.INSTANCE.showSurvey(this, R.id.container_survey_widget, WidgetType.SIMPLE)

Reward Listener - Client Side Callbacks

You can use .setOnRewardListener(onRewardListener) to set callback which receives the reward of the user and executes the behaviour you specify.

BitLabs.setOnRewardListener { payout -> Log.i(<TAG>, "Payout of: ${payout}") }

BitLabs.INSTANCE.setOnRewardListener(payout -> Log.i(<TAG>, "Reward payout: " + payout));

This callback is invoked when the user leaves the Offer Wall, and the payout is the total reward the user got since the Offer Wall is opened until it is closed.

📘

At the moment, the reward in this callback is just that of the surveys. For offers, please use the server-to-server callback.

🚧

We highly recommend using server-to-server callbacks instead! Please do not use this in apps where the user can withdraw real currency, as it might be exploitable.
However, if your app stores user data locally and does not sync with a server, this would be an option to still use BitLabs to reward your users.

Parameters

You can use .setTags(tags) to pass additional parameters to the OfferWall. The tags parameter is a HashMap<String, Object>.

val tags = mutableMapOf<String, Any>()
tags["display_mode"] = "offers"
tags["theme"] = "DARK"
BitLabs.tags = tags

Map<String, Object> tags = new HashMap<>();
tags.put("my_tag", "new_user");
tags.put("is_premium", true);
BitLabs.INSTANCE.setTags(tags);

🚧

Setting a new Map of Tags will replace the old ones.

Add a Parameter

Use addTag(key, value) if you want to append new tags to an already existent Map of tags which you already set earlier.

BitLabs.addTag("display_mode", "offers")
BitLabs.addTag("theme", "DARK")

BitLabs.INSTANCE.addTag("my_tag", "new_user");
BitLabs.INSTANCE.addTag("is_premium", true);

📘

Helpful

You can find a list of existing parameters here.

Leaderboard

The Leaderboard widget shows your top 100 earning users and their corresponding earnings in your app's currency. And will open the Offerwall if clicked.

Reward

The rewards shown in the widget are custom to your app and will be paid by us to you and your users. By default these rewards are disabled and not shown so this widget only serves the purpose to display the best earning users. To enable the rewards and incentivise your users to do more surveys and offers in your app please contact us on: [email protected]

The earnings will reset at the end of each month and the top 100 users will get their corresponding reward. If a user is listed in the leaderboard it will see it's rank by the blue (You) besides the username.

All earnings and rewards in the leaderboard will be formatted as your app's settings set on our publisher dashboard.

Username

If you implement the leaderboard without updating your offerwall and widget integration all users will just be called anonymous. To pass us the correct usernames to your provided user id you will have to add a tag with key username before launching the offerwall.

Implementation

getLeaderboard (DEPRECATED)

You can use getLeaderboard(onResponseListener) to get a LeaderboardFragment which you can add to any view in your Activity.

BitLabs.getLeaderboard {
	it?.let { leaderboardFragment ->
		context.supportFragmentManager
			.beginTransaction()
			.add(R.id.fragment_container_view_tag, leaderboardFragment)
			.commit()
	}
}

BitLabs.INSTANCE.getLeaderboard(leaderboardFragment -> {
	if (leaderboardFragment == null) return;

	getSupportFragmentManager()
		.beginTransaction()
		.add(R.id.fragment_container_view_tag, leaderboardFragment)
		.commit();
});

showLeaderboard

You can use showLeaderboard(<FragmentActivity>, <ContainerResId>) to show the Leaderboard Widget Fragment

1. FragmentActivity: The Activity where the container exists.
2. ContainerResId: The Resource Id that you added to the container where the Fragment will appear. You have to create this container in your Activity layout to let the SDK know where to render the Widget. It can be a normal View or FragmentContainer

// This usage assumes that the method is being called from within a class 
// that is of/inherits from type FragmentActivity
BitLabs.showLeaderboard(this, R.id.container_leaderboard)

// This usage assumes that the method is being called from within a class 
// that is of/inherits from type FragmentActivity
BitLabs.INSTANCE.showLeaderboard(this, R.id.container_leaderboard)

Whitelist HTTP Domains

Since BitLabs works with a plethora of survey providers, we can't always make sure that the domains are secured with HTTPS schemes. So we had to whitelist some providers.

If you want to remove or add a domain to the list:

1. Download the network_security_config.xml
2. Put the downloaded file inside [ProjectRootDirectory]/android/app/src/main/res/xml/
3. Now you can add or remove to it any domain you want.

Complete the Google Play Data Safety questionnaire

Once you are ready to launch your app, you should adjust the Google Play Data Safety questionnaire in order to get your app published on Google Play. Read about it here: https://developer.bitlabs.ai/docs/complete-the-google-play-data-safety-questionnaire