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.

Installing the BitLabs SDK

You can download the latest version of our Unity SDK from the Unity Asset Store.

❗️

Important

1. You have to always include the Editor in the plugins folder.

2. For Android, you must assign the Target API Level to API Level 31 or later.
   It can be changed in File > Build Settings > Player Settings > Other Settings

Initiating the SDK

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

// Start is called before the first frame update
void Start()
{
  BitLabs.init("YOUR-TOKEN", "YOUR-USER-ID");
}

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.

Using the SDK

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

👍

We're done!

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

Check if there's something to do for the user

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

// Check for available Surveys
// Set the name of the GameObject where you would like to receive the callback
BitLabs.checkSurveys(gameObject.name);

// Create a receiver Method
public void checkSurveysCallback(string surveyAvailable)
{
  Debug.Log("BitLabs Unity checkSurveys: " + surveyAvailable);
}

This function will invoke a callback called checkSurveysCallback(), so you should implement this method in the same class of the GameObject.

The callback's parameter is a string with value of "true" whenever there's a survey or a qualification question available for the user, "false" otherwise. It will return "null" if an error is raised and logged into the console.

Get Surveys Natively

You can use .getSurveys() to get a list(array) of available Surveys for the user.

// Get available Surveys 
// Set the name of the GameObject where you would like to receive the callback
BitLabs.getSurveys(gameObject.name);

public void getSurveysCallback(string surveysJson)
{
  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);
  }
}

// This class is used as a wrapper to deserialise the JSON Array of Surveys
// It's necessary if you're using JsonUtility for Deserialisation
// If you use another Library or namespace, then you may not need such a class
[System.Serializable]
class SurveyList
{
    public Survey[] surveys;
}

This function will invoke a callback called getSurveysCallback(), so you should implement this method in the same class of the GameObject.

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 accept Json Array as the wrapper, we had to created a SurveyList class. However, you can use any implementation you have to deserialise the JSON array into an array of Surveys.

Reward Callback

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

// Set the name of the GameObject you would like to receive the feedback
BitLabs.setRewardCallback(gameObject.name);

// Create a receiver Method
public void rewardCallback(string payout)
{
  Debug.Log("BitLabs Unity onReward: " + payout);
}

This function will store a callback called rewardCallback(), so to use it, you should implement this method in the same class of the GameObject.

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.

Tags - Add Tags to receive in your callbacks

You can use .addTag() to pass additional parameters to the SDK you would like to receive in your server-to-server callback.

// Additional Callback Tags
BitLabs.addTag("userType", "new");
BitLabs.addTag("isPremium", "false");