Android SDK v2
This page will guide you through the integration of our Android SDK into your app.
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.
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
// Note that the artifactId has changed here
implementation 'com.github.BitBurst-GmbH.bitlabs-android-library:core:2.2.9
'
// other dependencies
}
dependencies {
// other dependencies
implementation("com.github.BitBurst-GmbH.bitlabs-android-library:core:2.1.1")
// 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.
Deprecation
The older
init()
, shown below, is deprecated and will be remove in a future major release. You can use it for you need to know that in order to get the most out of BitLabs Offers, you have to to use the newinit()
function
BitLabs.init("YOUR-TOKEN", "YOUR-USER-ID")
BitLabs.INSTANCE.init("YOUR-TOKEN", "YOUR-USER-ID");
You can also hold the reference of
BitLabs.INSTANCE
in a global or local variable like this:BitLabs bitLabs = BitLabs.INSTANCE
And now you can use the library as
bitLabs.init("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()
to check if a survey is available for the user. This function will return true
whenever there's a survey or a qualification question available for the user. Otherwise, it will return false
.
BitLabs.checkSurveys { hasSurveys ->
if (hasSurveys == null) {
Log.e(<TAG>, "Error in HTTP, Check BitLabs Logs")
[email protected]
}
Log.i(<TAG>, hasSurveys ? "Has Surveys" : "No Surveys Available")
}
BitLabs.INSTANCE.checkSurveys(hasSurveys -> {
if(hasSurveys == null) {
Log.e(<TAG>, "Error in HTTP, Check BitLabs Logs");
return
}
Log.i(TAG, hasSurveys ? "Has Surveys" : "No Surveys Available");
});
If hasSurveys is null, then there has been an error in the request. It should be logged under the BitLabs TAG.
Get Surveys Natively
You can use .getSurveys()
to get available surveys for the user.
BitLabs.getSurveys { surveys ->
if (surveys == null)
Log.i(<TAG>, "NULL - Check BitLabs Logs");
else {
Log.i(<TAG>, "Surveys: $surveys");
surveys.get(0).open(this);
}
}
BitLabs.INSTANCE.getSurveys(surveys -> {
if (surveys == null)
Log.i(<TAG>, "NULL - Check BitLabs Logs");
else {
Log.i(<TAG>, "Surveys: " + surveys);
surveys.get(0).open(this);
}
});
The callback's parameter is a List of Surveys. A Survey has the following properties:
Property | Type | Description |
---|---|---|
networkId | Int | The id of the Network this survey belongs to. |
id | Int | The id of the Survey. |
cpi | String | CPI of this survey in USD without any formatting applied. |
value | String | CPI formatted according to your app settings. Can be shown to the user directly. |
loi | Double | Assumed length of the survey in minutes. |
remaining | Int | Amount of users that can still open the survey |
details | Details(Category(name: String, IconUrl: String)) | The details of the category this Survey is classified in. |
rating | Int | Difficulty ranking of this survey. 1-5 (1 = hard, 5 = easy). Minimum value is 1, maximum value is 5. |
link | String | This link can be used as is to open the survey. All relevant details are inserted on the server. |
missingQuestions | Int? | The amount of questions that have to be answered before the survey is guaranteed to be openable by the user. |
open() | Function | A function which opens the Offerwall. |
Reward Listener - Client Side Callbacks
You can use .setOnRewardListener()
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.
Tags - Set a list of Tags to receive in your callbacks
You can use .setTags()
to pass additional parameters to the SDK you would like to receive in your callback.
val tags = mutableMapOf<String, Any>()
tags["my_tag"] = "new_user"
tags["is_premium"] = true
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 Tag - Add single tags to receive in your callbacks
Use addTag()
if you want to append new tags to an already existent Map of tags which you already set earlier
BitLabs.addTag("my_tag", "new_user")
BitLabs.addTag("is_premium", true)
BitLabs.INSTANCE.addTag("my_tag", "new_user");
BitLabs.INSTANCE.addTag("is_premium", true);
Updated 25 days ago
You have now implemented BitLabs with your project. If you haven't done it already, it is time to configure server-to-server callbacks and the look and feel of your app.