SDK usage (Kotlin)

getInstance()

In order to use BotProtection, it is enough to create the instance of BotProtection class:

val botProtection = BotProtection.getInstance()

start()

To start collecting data for identifying bots and sending them to the server, you need to call start().

Here's an example on start() method on how to activate BotProtection SDK and begin to collect data when the app is started:

 class ApplicationExample: Application() {

    val botProtection by lazy {
        BotProtection.getInstance()
    }
    
    override fun onCreate() {
        super.onCreate()
        
        botProtection
            .sendUUID("uuid")
            .start()
    }
    
    // ...
}

First, we need to create an instance of BotProtection:

val botProtection by lazy {
    BotProtection.getInstance()
}

To start collecting data, use:

botProtection
    .sendUUID("uuid")
    .start()

It collects data until the stop() method happens.

sendUUID()

The sendUUID method accepts a value of type String.

UUID is a unique user identifier that will allow users to be correlated with anonymised analysed users in the system.

UUID can be generated independently, or send an encrypted identifier associated with the user.

Note: you need to call this method at the moment when the user is logged into the account and before the stop() method is called, which will completely stop the SDK.

botProtection.sendUUID("uuid")

If the UUID is known at the time start() is done, then you can start the library in this way, initially reporting the UUID:

botProtection
    .sendUUID("uuid")
    .start()

stop()

The stop() method should be called if it is necessary to completely stop data collection, disable BotProtection and immediately send data to the server.

Note: In order to start collecting data again and sending them for analysis, you need to call start().

 botProtection
     .setMode(Mode.NO_TOKEN) \\ or Mode.WITH_TOKEN
     .setListener(botProtectionListener)
     .stop()

Mode may contain the following values:

Command	Description
NO_TOKEN	Enable a NoToken mode which sends data to BotProtection machine and stops the lib. This mode is useful when you need to analyse traffic from your app.
WITH_TOKEN	Is useful when JWT token is planned to be passed to the backend side to actively defend from bots For example, it is used in a process of creation of a new user.

setListener()

In order to get results of BotProtection behaviour analysis, you can use the callback BotProtectionListener. This method works same as regular start().

.setListener(object : BotProtectionListener {
    override fun onSuccess(botProtectionResult: BotProtectionResult) {
		    Log.i(TAG, "challengeId: ${botProtectionResult.challengeId}, "
		            + "token: ${botProtectionResult.token}")
    }

    override fun onError(result: BotProtectionError) {
        Log.e(TAG, botProtectionError.name)
    }
})

Command	Description
challengeId	It's a unique identifier for the user's verification which can be sent to a server to get results (not mandatory since you can get result by UUID)
token	is received if WITH_TOKEN mode is set. Is used for proactive bot prevention.

BotProtectionError may contain the following values:

Value	Description
SUCCESS	Data collected and sent
CONNECTION_ERROR	Connection error
INVALID_DATA	Data Processing Error
BP_KEY_NAME_NOT_FOUND	No ApiKey found in meta-data
BP_KEY_NAME_NULL_POINTER	ApiKey is NULL
BP_KEY_INCORRECT	ApiKey is incorrectly recorded, copy it again from the console
UNKNOWN	Unknown error