[Документация Yandex Cloud](../../index.md) > [Yandex SmartCaptcha](../index.md) > Концепции > Варианты заданий

# Варианты заданий

{% note info %}

Функциональность вариантов заданий и правил показа находится на стадии [Preview](../../overview/concepts/launch-stages.md).

{% endnote %}

_Варианты заданий_ — разные капчи, которые можно показывать в зависимости от базовых параметров входящих запросов. Для гибкого разделения запросов используются комбинации [условий на трафик](#traffic-conditions).

Если разделение капчи не требуется, настраивают только вариант [по умолчанию](../operations/create-captcha.md). Для всех вариантов можно выбрать основное и дополнительное задание, а также сложность капчи. Внешний вид всех вариантов капчи остается единым.

Варианты заданий позволяют адаптировать капчу в зависимости от вероятности угрозы и улучшить пользовательский опыт.

## Преимущества использования вариантов капчи {#why-use-variants}

* Сегментированная защита от угроз.
  
  Разные пользователи и источники трафика представляют разный уровень угрозы. Боты и злоумышленники могут использовать специфические IP или иметь определенные атрибуты в заголовке запроса. Учитывая эти особенности, подозрительному трафику можно назначать более сложные проверки.

* Формирование позитивного пользовательского опыта.
  
  Сложная капча доставляет неудобства пользователям и снижает впечатление от сайта. Поэтому в зависимости от платформы пользователя можно показывать более удобную для прохождения капчу. Например, на мобильных платформах показывать слайдер, на стационарных — чекбокс. Это повышает комфорт работы и увеличивает лояльность пользователей.

## Правила показа {#captcha-view-rules}

В список правил уже добавлено правило по умолчанию, которое показывает капчу по умолчанию. Оно применяется к трафику, если не будет найдено других подходящих правил. Удалить правило по умолчанию нельзя.

Правило показа капчи позволяет настроить:

* _Вариант задания_ — капча, которая будет показана пользователю.
  
  Если вариант задания используется в правиле, удалить вариант нельзя.
  
* _Приоритет правила_ — порядок проверки правил. Может принимать значения от `1` до `999999`. Приоритет правила по умолчанию — `1000000`, его нельзя изменить.
  
  Правила проверяются в порядке приоритета от меньшего к большему: `1`, `2` и так далее до `1000000`. Если трафик соответствует нескольким правилам, к нему применится первое сработавшее правило.
  
* _Условия для входящего трафика_ — набор параметров входящего трафика:
  * `IP` — IP-адрес, диапазон адресов или регион IP-адресов. 
    
    Вы можете добавить или исключить IP-адрес, диапазон адресов или регион из правила показа капчи. Например, диапазон доверенных IP-адресов ваших клиентов или регионы, из которых наиболее часто происходят атаки на ваш сайт.

  * `HTTP header` — параметр в заголовке HTTP.

    Вы можете выбрать разную капчу в зависимости от устройства или браузера, с которого поступил запрос от пользователя. Также по `HTTP header` можно определить источник перехода, сведения об авторизации и другие данные.
  
  * `URI` — путь, по которому направлен входящий запрос к сайту.

    Для важных страниц, например аутентификации или платежа, можно настроить сложную капчу.

  * `Host` — домен, на который пришел запрос.

  * `Metadata` — дополнительные данные, передаваемые с фронтенда.

В правиле можно задать одно или несколько разных условий. Также можно добавить несколько условий одного типа с помощью операторов `и` или `или`.

### Добавление и проверка метаданных {#metadata}

Параметр `metadata` позволяет передавать с фронтенда в капчу собственные дополнительные данные, например информацию о пользователе или результаты системы [антифрода](https://ru.wikipedia.org/wiki/Антифрод). Так можно настраивать правила показа разных типов заданий, например выдавать более сложную капчу для подозрительных пользователей.

Сохраняйте выданные значения `metadata` на бэкенде и сверяйте их при валидации токена капчи, чтобы защититься от подделки метаданных злоумышленниками,

Общая длина всех ключей и значений в `metadata` не должна превышать 512 символов.

Пример добавления капчи с метаданными:

```javascript
window.smartCaptcha.render(container, {
  sitekey: sitekey,
  hl: language,
  callback: callback,
  metadata: {
    key1: 'value-1',
    key2: 'value-2',
  }
});
```

{% cut "Схема проверки капчи с метаданными" %}

[Схема в отдельном окне](metadata-scheme.md)

```mermaid
sequenceDiagram
    %% Участники процесса
    participant Backend as Бэкенд сайта
    participant Antifraud as Антифрод
    participant Frontend as Фронтенд сайта
    participant User as Пользователь
    participant CaptchaBackend as Yandex Cloud
    participant DB as База данных

    %% Ход выполнения
    Note over Backend: Решение показать<br/>капчу
    Backend->>Antifraud:  
    Note over Antifraud: Определение<br/>категории<br/>пользователя
    Antifraud->>Backend:  

    Note over Backend: Генерация параметров<br/>metadata ={<br/>"key": <unique_key>,<br/>"category": <category>, }
    
    Backend->>DB:  
    Note over DB: Сохранение<br/>метаданных

    Backend->>Frontend:  
    Note over Frontend: Рендеринг капчи<br/>с метаданными
    
    Frontend->>User:  
    
    Note over User: Выполнение капчи с<br/>этими метаданными<br/>(или другими) и <br/>получение справки
    User->>CaptchaBackend:  
    
    Note over CaptchaBackend: Генерация справки<br/> с метаданными
    CaptchaBackend->>User:  

    User->>Frontend:  
    Frontend->>Backend:  
    
    Note over Backend: Отправка запроса<br/>для проверки

    Backend->>CaptchaBackend:  
    Note over CaptchaBackend: /validate<br/>в ответе содержатся<br/> метаданные из справки
    CaptchaBackend->>Backend:  

    Note over Backend: Проверка ответа /validate

    Note over Backend: Сверка полученных<br/>метаданных<br/>с метаданными<br/>в БД (опционально)
    
    Backend->>DB:  
    Note over DB: Удаление<br/>метаданных
```

{% endcut %}

## Условия на трафик {#traffic-conditions}

#|
|| **Тип и виды сопоставления** | **Значения (пример)** | **Оператор** ||
|| `IP` 
* Совпадает или принадлежит диапазону
* Не совпадает и не принадлежит диапазону
* IP принадлежит региону
* IP не принадлежит региону
|
* IP-адрес (`1.2.33.44`).
* [CIDR](https://ru.wikipedia.org/wiki/Бесклассовая_адресация) (`10::1234:1abc:1/64`).
* Диапазон адресов (`1.2.0.0-1.2.1.1`).
* Двухбуквенный код страны по [ISO 3166-1 alpha-2](https://ru.wikipedia.org/wiki/ISO_3166-1_alpha-2) (`ru`, `kz`).
| _или_ ||
|| `HTTP header` 
* Совпадает с
* Не совпадает с
* Начинается с
* Не начинается с
* Соответствует регулярному выражению
* Не соответствует регулярному выражению
|
Формат `ключ: значение`, где:
* `ключ` — HTTP-заголовок.
* `значение` — конкретное значение заголовка, префикс значения или [регулярное выражение](https://ru.wikipedia.org/wiki/Регулярные_выражения) библиотеки [PIRE](https://github.com/yandex/pire).

Например, `User-Agent: curl/7.55.1`.
| _и_ ||
|| `URI` 
* Совпадает с
* Не совпадает с
* Начинается с
* Не начинается с
* Соответствует регулярному выражению
* Не соответствует регулярному выражению
| 
Путь запроса, начало пути запроса или регулярное выражение библиотеки PIRE.

Например, `/`.
| Не применяется ||
|| `Host` 
* Совпадает с
* Не совпадает с
* Начинается с
* Не начинается с
* Соответствует регулярному выражению
* Не соответствует регулярному выражению
|
Значения заголовка `Host` для HTTP/1.1 или псевдозаголовка `authority` для HTTP/2, по которому выбирается виртуальный хост, префикс значения или регулярное выражение библиотеки PIRE.

Например, `example.com`.
| _или_ ||
|| `Metadata`
* Совпадает с
* Не совпадает с
* Начинается с
* Не начинается с
* Соответствует регулярному выражению
* Не соответствует регулярному выражению
|
Дополнительные данные, передаваемые с фронтенда в формате `ключ: значение`, где:
* `ключ` — ключ параметра.
* `значение` — конкретное значение, префикс значения или регулярное выражение библиотеки PIRE.

Например, `user_type: premium` или `risk_score: high`.
| _и_ ||
|#