CHANGELOG

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

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 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.

Native Survey Widgets

To add Native Survey Widgets, add its Prefab, called SurveyWidgets, to your UI. The Prefab is found in Source > Prefabs > SurveyWidgets. After you add it, you can use SurveyContainer GameObject in your code to populate it with surveys.

GameObject container = GameObject.Find("SurveyContainer");
SurveyContainer containerScript = container.GetComponent<SurveyContainer>();
containerScript.UpdateList(surveyList.surveys);

Widget Types

Now, you can choose a widget type of three, SimpleWidget, CompactWidget, or FullWidthWidget:

1. press on the SurveyWidgets in your Hierarchy.
2. In the Inspector expand the SurveyContainer Script Component.
3. Choose the type you want in the Prefab property.

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.

Parameters - Add Tags to receive in your callbacks

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

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

📘

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

To add the Leaderboard, add its Prefab, called Leaderboard, to your UI. The Prefab is found in Source > Prefabs > Leaderboard. After you add it, you will have to call GetLeaderboard(gameObject.name) on the Start() of the GameObject Script.

void Start()
{
  //initialisation code here
  
  GetLeaderboard(gameObject.name);
}

private void GetLeaderboardCallback(string leaderboardJson)
{
  Leaderboard leaderboard = JsonUtility.FromJson<Leaderboard>(leaderboardJson);
  GameObject leaderboardContainer = GameObject.Find("Leaderboard");
  LeaderboardScript leaderboardScript = leaderboardContainer.GetComponent<LeaderboardScript>();
  leaderboardScript.UpdateRankings(leaderboard.topUsers, leaderboard.ownUser);
}

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

The callback's parameter is a string with a JSON Object. This object can be deserialised into a Leaderboard C# object. Then the LeaderboardScript class is acquired from the GameObject and the UpdateRankings with the topUsers and ownUser parameters.