> For the complete documentation index, see [llms.txt](https://docs.mobguards.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mobguards.com/en/android-usage/sdk-usage-kotlin.md).

# SDK usage (Kotlin)

### getInstance()

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

```kotlin
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:

```java
 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`:

```kotlin
val botProtection by lazy {
    BotProtection.getInstance()
}
```

To start collecting data, use:

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

```kotlin
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:

```kotlin
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()`.

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

`Mode` may contain the following values:

| Command     | Description                                                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NO\_TOKEN   | <p>Enable a NoToken mode which sends data to BotProtection machine and stops the lib.</p><p>This mode is useful when you need to analyse traffic from your app.</p> |
| 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()`.

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