# Использование SDK

### **Импорт библиотеки**

В файлы, из которых идет обращение к `BotProtection`, необходимо импортировать библиотеку

```swift
import BotProtection
```

### **configure(withApiKey apiKey: String)**

Перед использованием библиотеки необходимо настроить API Key

```swift
BotProtection.configure(withApiKey: "your-bp-api-key-here")
```

### **start()**

Чтобы начать сбор данных для идентификации ботов и отправки их на сервер, вам нужно вызвать функцию `start()`.

Вот пример метода `start()`, при котором `BotProtection SDK` активируется и начинает собирать данные в момент запуска приложения:

```swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        BotProtection.configure(withApiKey: "your-bp-api-key-here")
        BotProtection.sendUUID("user-uuid")
        BotProtection.start()
        return true
}
```

Сначала нужно сконфигурировать экземпляр `BotProtection`:

```swift
BotProtection.configure(withApiKey: "your-bp-api-key-here")
BotProtection.sendUUID("user-uuid")
```

Чтобы начать сбор данных, используйте:

```swift
BotProtection.start()
```

`BotProtection` собирает данные до тех пор, пока не произойдет метод `stop()`.

### **sendUUID(\_ uuid: String)**

Метод `sendUUID` принимает значение типа `String`.

**UUID** - это уникальный идентификатор пользователя, который позволяет соотносить пользователей с анонимными проанализированными пользователями в системе.

**UUID** может генерироваться независимо или отправлять зашифрованный идентификатор, связанный с пользователем.

**Примечание:** Этот метод необходимо вызывать в момент входа пользователя в учетную запись и перед вызовом метода `stop()`, который полностью остановит SDK.

```swift
BotProtection.sendUUID("user-uuid")
```

Если UUID известен во время выполнения `start()`, вы можете запустить библиотеку следующим образом, сначала сообщив UUID:

```swift
BotProtection.configure(withApiKey: "your-bp-api-key-here")
BotProtection.sendUUID("user-uuid")
BotProtection.start()
```

### **stop(needToken: Bool, \_ completion: @escaping (\_ challengeID: String?, \_ token: String?, \_ error: BPError?) -> Void)**

Метод `stop()` следует вызывать, если необходимо полностью остановить сбор данных, отключить `BotProtection` и немедленно отправить данные на сервер.

**Примечание:** Чтобы снова начать сбор данных и отправку их на анализ, необходимо вызвать `start()`.

```swift
BotProtection.stop(needToken: true/false) { [weak self] (challengeId, token, error) in
    guard let self = self else { return }
    
    // process error here
    // process challengeId
    // process token (if needToken = true)
}
```

| Параметр            | Результат                                                                                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `needToken = false` | <p>Включается режим NoToken, который отправляет данные на BotProtection machine и останавливает библиотеку. </p><p>Этот режим полезен, когда вам нужно проанализировать трафик из вашего приложения.</p> |
| `needToken = true`  | <p>Полезно, когда токен JWT планируется передать бэкенду для активной защиты от ботов.</p><p>Например, такой подход используется используется в процессе создания нового пользователя на клиенте.</p>    |

**Параметры completion**

| Параметр      | Описание                                                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `challengeId` | Уникальный идентификатор для подтверждения пользователя, который можно отправить на сервер для получения результатов (не обязательно, поскольку вы можете получить результат по UUID) |
| `token`       | Принимается, если используется режим needToken = true. Используется для активного препятствия ботам                                                                                   |
| `error`       | Ошибка при отправке данных                                                                                                                                                            |

**BPError может содержать следующие значения:**

| **Значение**  | **Описание**            |
| ------------- | ----------------------- |
| `invalidData` | Ошибка обработки данных |
| `unknown`     | Неизвестная ошибка      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mobguards.com/ru/ios-usage/ispolzovanie-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.