CHANGELOG

View the complete changelog on GitHub Releases or in the package CHANGELOG.md file.

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.

📘
Migrating from v3?
See the Migration Guide for detailed upgrade instructions.

Installing the BitLabs SDK

Prerequisites

This SDK requires External Dependency Manager for Unity (EDM4U) to resolve Android and iOS native dependencies.

Install EDM4U first:

Add to your Packages/manifest.json:

{
  "dependencies": {
    "com.google.external-dependency-manager": "https://github.com/googlesamples/unity-jar-resolver.git?path=upm#v1.2.186"
  }
}

Or download the unitypackage from their Repo.

Option 1: Install via UPM (Unity Package Manager) - Recommended

Add to your Packages/manifest.json:

{
  "dependencies": {
    "com.prodege.bitlabs": "https://github.com/BitBurst-GmbH/bitlabs-unity.git#v4.0.0"
  }
}

Or install the latest version:

{
  "dependencies": {
    "com.prodege.bitlabs": "https://github.com/BitBurst-GmbH/bitlabs-unity.git#upm"
  }
}

Option 2: Install via .unitypackage

Download the latest .unitypackage from Releases
Import into your Unity project: Assets → Import Package → Custom Package

Android Requirements

For Android, you must set:

Minimum API Level: 21 or higher
Target API Level: 35 or higher
Compile SDK: 35

Configure in: Edit → Project Settings → Player → Android → Other Settings

Note: Unity 2023.1+ handles these automatically. For Unity 2021.3 - 2022.3, manual configuration is required.

Initiating the SDK

You will need to initiate the SDK before you can use it. You can do so with the following code.

void Start()
{
    BitLabs.Init("YOUR_API_TOKEN", "USER_ID",
        onSuccess: () =>
        {
            Debug.Log("BitLabs SDK initialized successfully!");
        },
        onError: (error) =>
        {
            Debug.LogError($"BitLabs initialization failed: {error}");
        }
    );
}

This is where you will need the API key from the dashboard, as you will need to replace "YOUR_API_TOKEN" with it. For "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.

Callbacks:

onSuccess: Called when the SDK is initialised successfully. Use this to know when BitLabs is ready.
onError: Called if initialisation fails, providing an error message. Use this to handle initialization errors gracefully.

Using the SDK

Show BitLabs Offerwall 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.LaunchOfferWall();

👍
We're done!
Theoretically, this is all you have to do. Anything below is optional but can improve the user experience.

Check if surveys are available

You can use .CheckSurveys() to check if a survey is available for the user.

BitLabs.CheckSurveys(
    onSuccess: (hasSurveys) =>
    {
        if (hasSurveys)
        {
            Debug.Log("Surveys are available!");
        }
        else
        {
            Debug.Log("No surveys available at the moment.");
        }
    },
    onError: (error) =>
    {
        Debug.LogError($"BitLabs CheckSurveys failed: {error}");
    }
);

Callbacks:

onSuccess: Called with a boolean indicating if surveys are available (true) or not (false).
onError: Called if the check fails, providing an error message.

Get Surveys Natively

Instead of showing the OfferWall in a WebView, you can request the surveys and show them natively.

BitLabs.GetSurveys(
    surveys => {
        // Handle surveys list
        SurveyList surveyList = JsonUtility.FromJson<SurveyList>("{ \"surveys\": " + surveysJson + "}");
        foreach (var survey in surveyList.surveys)
        {
            Debug.Log("Survey Id: " + survey.id + ", in Category: " + survey.details.category.name);
        }
    },
    error => {
        // Handle error
        Debug.LogError($"Error getting surveys: {error}");
    }
);

Callbacks:

onSuccess: Called with List<Survey> containing available surveys
onError: Called with error message string if request fails

The callback's parameter is a string with a JSON Array of Survey objects. It would be empty if no surveys exist(i.e. there are unanswered qualification questions).

📘
The implementation we have of the callback is just one of many. We just used JsonUtility to deserialise the Json Array into an Array of Surveys. But since JsonUtility doesn't deserialise Json Arrays, we had to create a SurveyList class as a Wrapper for the Array. However, you can use any implementation you have to deserialise the JSON array into an array of Surveys.

Survey Object Properties:

id: Unique survey identifier
value: Reward value in your currency
loi: Length of Interview (estimated completion time in minutes)
rating: Survey quality rating
category: Survey category/type
link: Direct URL to launch this specific survey

Reward Callback

You can use .SetRewardCallback() to receive callbacks to reward the user

BitLabs.SetRewardCallback(onReward: (payout) => {
    Debug.Log($"User earned reward: {payout}");
    // Update user balance, show notification, etc.
});

Note: The callback receives the payout amount (as double) directly. You can call SetRewardCallback() any time after initialisation. Previous callbacks are replaced when calling this method again.

📘
Note:

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

You can call SetRewardCallback() any time after initialisation. Previous callbacks are replaced when calling this method again.

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.

🚧
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 - Add Tags

You can use .AddTag() to pass additional parameters to the OfferWall.

// Additional Callback Tags
BitLabs.AddTag("display_mode", "offers");
BitLabs.AddTag("theme", "DARK");

Other than the existing parameters, you can pass whichever you want to receive in the server-to-server callbacks.

📘
You can find a list of existing parameters here.

Demo Scene Reference

The SDK includes a complete demo scene showing all features and best practices for integration.

Importing the Demo

Open Unity Package Manager
Find BitLabs in the package list
Expand Samples section
Click Import next to "Demo Scene"

This imports the demo to Assets/Samples/BitLabs/[version]/Demo Scene/

What's Included

Demo Scene (DemoScene.unity):

Complete UI showing all BitLabs features
Button examples for each API method
Console logging for all callbacks
Error handling demonstrations

Demo Script (Demo.cs):

Reference implementation of all SDK methods
Proper initialization flow
Callback handling examples
Tag setting examples
Reward listener setup

Using the Demo

Import demo as described above
Open DemoScene.unity
Select the BitLabs GameObject in hierarchy
In Inspector, set your API Token (get from BitLabs Dashboard)
Set a test User ID
Run the scene and test all features

iOS Tracking Authorization

Starting with iOS 14.5, apps must request user permission before tracking them across apps and websites (ATT - App Tracking Transparency).

BitLabs.RequestTrackingAuthorization();

Then add the following key to Info.plist:, providing the custom message you want.

<key>NSUserTrackingUsageDescription</key>
<string>We use tracking to provide you with better offers and rewards</string>

Gaming offers on iOS

To enable gaming offers for SDK integrations on iOS, you need to follow this guide.