iOS SDK v2

This page will guide you through the implementation of our iOS SDK.

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.

Adding the SDK

Add a Podfile with BitLabs framework as a pod reference.

# Installing the SDK as pod reference
# You can specify the version you want or just add 'BitLabs' for the latest version 
pod 'BitLabs', '~> 2.1.0'

Configuring the SDK

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

BitLabs.shared.configure(token: "YOUR_TOKEN", uid: "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.

πŸ“˜

New Invocation Syntax

As you can see, the invocation syntax changed. We have made the BitLabs class a singleton, so now you will have only one shared instance throughout the whole lifecycle of your main process(application). This instance is accessed via BitLabs.shared.

πŸ“˜

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

let bitLabs = BitLabs.shared

And now you can use the library as

bitLabs.configure(token: "YOUR_TOKEN", uid: "YOUR_USER_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.shared.launchOfferWall(parent: <UIViewController>)

The <UIViewController> is the one used to present the WebView of the Offer Wall.

🚧

Note

Upon closing the Offer Wall(i.e. the WebView), several Assertion Errors will be printed into the console. These errors seem to be caused by some background process from iOS trying to communicate with the closed WebView and we can't control iOS. As per our testing, these errors do not have any practical effect on the library. So you can ignore them.

For more info check this StackOverFlow Answer.

πŸ‘

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 .hasSurveys() to check if a survey is available for the user. This function returns true whenever there's at least one survey or qualification question available for the user. Otherwise, it returns false.

BitLabs.shared.checkSurveys { hasSurveys in
  if hasSurveys {
    print("Surveys available!")
  } else {
    print("No surveys available!")
  }
}

Get Surveys

You can use '.getSurveys()' to get available surveys for the user.

BitLabs.shared.getSurveys { surveys in
    print("[Example] \(String(describing: surveys))")
    
    surveys?[0].open(parent: self)
}

The callback's parameter is a List of Surveys. It would be empty if no surveys exist(i.e. there are unanswered qualification questions). A Survey has multiple properties and a method called open(). The open() method opens the Offerwall for now.

Reward Completion Handler - Client Side Callbacks

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

BitLabs.shared.setRewardCompletionHandler { payout in
    print("Your 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.

🚧

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 .setTags() to pass additional parameters to the SDK you would like to receive in your callback.

BitLabs.shared.setTags(["userType": "New", "isPremium": false])

🚧

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

Add Tag - Add single tags to receive in your callbacks

Use .addTag() if you want to append new tags to an already existent dictionary of tags which you already set earlier.

BitLabs.shared.addTag(key: "userType", value: "New")
BitLabs.shared.addTag(key: "isPremium", value: false)

Your next Step

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.

Did this page help you?