Документация

Защита отличает людей от ботов и умеет четыре вещи: оценивать каждого посетителя, показывать капчу подозрительным перед отправкой формы, запускать счётчики аналитики только для людей и проверять заявки на спам по API.

Быстрый старт

Войдите в кабинет аккаунтом ДАРА (тот же, что в ДАРА Аналитике и Отпечатке; если аккаунта нет — он создастся при первом входе).
Нажмите «Добавить сайт» и укажите домены: site.ru — сам сайт и www.site.ru, *.site.ru — ещё и все поддомены.
Вставьте код со вкладки «Код и ключи» на все страницы — в <head> или перед </body>:
```
<script src="https://captcha.daratech.ru/s/dz_ВАШ_КЛЮЧ.js" async></script>
```
Откройте сайт — на вкладке «Обзор» появятся визиты. Сайт начинает в режиме «Только считать»: смотрите, сколько ботов и спама, и включайте нужное.

Больше на сайте ничего менять не нужно: настройки скрипт получает с нашего сервера, изменения в кабинете доходят до сайта примерно за минуту. Если на сайте настроена CSP, разрешите captcha.daratech.ru в script-src и connect-src.

Режимы

Режим	Что происходит
Только считать	Защита оценивает посетителей и заявки, но ничего не блокирует: капча не показывается, API всегда отвечает `"action": "deliver"`. В журнале видно, что было бы отклонено. С этого режима начинает каждый сайт.
Боевой	Подозрительным посетителям перед отправкой формы показывается капча, API отвечает `"action": "reject"` на явный спам.
Выключено	Аварийный выключатель на вкладке «Обзор»: скрипт ничего не делает, API пропускает все заявки. Код на сайте трогать не нужно.

Скоринг

Каждый визит получает оценку от 0 до 100: чем больше, тем вероятнее бот. Учитываются признаки браузера (управляемый или безоконный браузер, робот по User-Agent), сеть (IP дата-центра), частота визитов с одного IP и одного устройства по всей сети ДАРА, время, которое измеряет наш сервер (загрузка → первое действие → отправка формы), и сводка поведения (движения, набор, прокрутка).

Строгость задаёт пороги «подозрительно» и «бот»: мягко — 50 и 70, обычно — 40 и 60, строго — 30 и 50. Адреса из белого списка (офис, свои тесты) всегда считаются людьми. Настоящих поисковых роботов Яндекса, Google и Bing Защита узнаёт по обратному DNS и не показывает им капчу.

Защита форм

Скрипт сам находит формы с полями для текста, email или телефона, добавляет в них скрытое поле dara_token и невидимую ловушку _dz_hp (её заполняют только боты). При отправке скрипт спрашивает наш сервер, всё ли в порядке:

человек — форма уходит сразу, посетитель ничего не замечает;
подозрительный посетитель в боевом режиме — капча-пазл: поставить фигуру на место ползунком или стрелками клавиатуры;
капча решена — форма уходит; закрыта — не уходит; три ошибки — уходит с пометкой «капча не пройдена» (сервер сайта увидит это в проверке и отправит заявку в журнал).

Какие формы защищать, задаётся на вкладке «Защита форм»: все, только по CSS-селектору или все, кроме. Чтобы скрипт не трогал одну форму, добавьте ей data-dara="off".

Поле dara_token уходит на сервер сайта вместе с остальными полями. Чтобы проверка была полной, сервер передаёт его в API антиспама. Contact Form 7, формы Битрикса и обычные HTML-формы передают все поля сами.

Формы на JavaScript

Если форма отправляется своим кодом (fetch, XMLHttpRequest) и сама решает, какие поля отправить, получите токен перед отправкой и добавьте его в запрос:

const token = await DaraProtect.token();   // при необходимости покажет капчу
if (token === null) return;                 // посетитель закрыл капчу — не отправляем
body.dara_token = token;                     // пустая строка — сервер Защиты недоступен, отправляйте как есть
await fetch('/api/lead', { method: 'POST', body: JSON.stringify(body) });

DaraProtect.ready(fn) вызывает fn({class}), когда визит оценён (human, suspect или bot). DaraProtect.challenge() показывает капчу без подозрения — если нужна проверка вручную.

Аналитика для людей

Счётчики запускаются только для людей: сразу — если это ясно при загрузке страницы, иначе после первого настоящего действия посетителя (касание, прокрутка, клавиша) или через несколько секунд на открытой вкладке. Боты в отчёты не попадают. Визиты из рекламы (yclid, gclid, utm_medium=cpc и другие метки из настроек) считаются сразу, чтобы Директ не терял визиты и конверсии.

На вкладке «Аналитика для людей» укажите номера счётчиков Метрики (и параметры: Вебвизор, карта кликов, электронная коммерция), идентификаторы GA4, контейнер GTM или свой код.
Уберите с сайта родной код этих счётчиков. Иначе он посчитает и ботов. Если родной код остался, Защита это заметит и не запустит счётчик второй раз.
Вызовы ym(…, 'reachGoal', …) на сайте менять не нужно: пока Защита решает, они копятся в очереди и уходят после запуска счётчика.

В отчётах Метрики станет меньше визитов и отказов — это и есть убранные боты. Предупредите тех, кто смотрит отчёты, и сравнивайте периоды «до» и «после» с этой поправкой.

API антиспама

Сервер сайта отправляет заявку на проверку до того, как отправить её дальше. Ключ — секретный dzs_… со вкладки «Код и ключи», передаётся в заголовке Authorization: Bearer. Никогда не вставляйте его в код страницы.

POST`https://captcha.daratech.ru/api/v1/check`

{
  "token": "значение поля dara_token (или пусто)",
  "fields": {"name": "Анна", "email": "anna@mail.ru", "phone": "+7 912 000-00-00", "message": "…", "любое_поле": "…"},
  "ip": "IP посетителя",
  "user_agent": "User-Agent посетителя",
  "page_url": "https://site.ru/contacts/",
  "form": "contacts",
  "akismet": "spam"            // необязательно: решение Akismet, если он ещё стоит — для сравнения
}

Ответ:

{"check_id": "Vb3…", "verdict": "spam", "action": "reject", "score": 83,
 "reasons": ["no_interaction", "links_in_text"], "checked": "full", "mode": "live"}

Поле	Значение
`action`	`deliver` — отправляйте заявку как обычно; `reject` — не отправляйте (она уже в журнале Защиты). Ориентируйтесь на это поле.
`verdict`	`ok`, `suspect` (заявка доставляется, но подозрительна — можно пометить) или `spam`.
`checked`	`full` — с данными визита по токену; `partial` — токена не было, проверка по содержимому, IP и браузеру.
`mode`	`shadow` — режим «Только считать»: `action` всегда `deliver`.

Повтор того же токена в течение 30 минут возвращает тот же ответ — проверять одну заявку дважды безопасно.

Если Защита не ответила за несколько секунд или вернула ошибку, отправляйте заявку как обычно — с пометкой «не проверено». Терять настоящие заявки из-за нашего сбоя нельзя. Пример на PHP:

$ch = curl_init('https://captcha.daratech.ru/api/v1/check');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer ' . getenv('DARA_PROTECT_SECRET')],
    CURLOPT_POSTFIELDS => json_encode([
        'token' => $_POST['dara_token'] ?? '',
        'fields' => $_POST,
        'ip' => $_SERVER['REMOTE_ADDR'],
        'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
        'page_url' => $_SERVER['HTTP_REFERER'] ?? '',
    ]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
]);
$r = json_decode((string)curl_exec($ch), true);
if (($r['action'] ?? 'deliver') === 'reject') {
    exit;                                  // спам: не отправляем, заявка в журнале Защиты
}
$unchecked = !isset($r['action']);        // Защита не ответила — отправляем с пометкой
// … дальше как обычно: письмо, CRM, база

POST`https://captcha.daratech.ru/api/v1/feedback`

Отметка человека: {"check_id": "…", "label": "spam"} или "ham" (не спам). По отметкам строится сравнение с Akismet и видно, где Защита ошибается.

GET`https://captcha.daratech.ru/api/v1/ping`

Проверка ключа: {"ok": true, "site": "…", "mode": "shadow"}.

Журнал и возврат заявок

В журнале — заявки, которые Защита посчитала спамом за последние 30 дней (в режиме «Только считать» — те, что были бы отклонены). Данные заявок хранятся в зашифрованном виде и удаляются через 30 дней.

«Не спам — отправить дальше» отмечает заявку как настоящую и отправляет её на email и/или вебхук с вкладки «Антиспам». Вебхук получает POST с JSON: {"event": "lead_restored", "check_id", "site", "created_at", "fields", "page_url", "referer"}; адрес — только https:// в интернете.

Переход с Akismet

Оставьте Akismet включённым и поставьте Защиту в режиме «Только считать».
Передавайте решение Akismet в проверку полем akismet — и отправляйте в Защиту все заявки, в том числе те, что Akismet посчитал спамом.
Отмечайте ошибки в журнале (или через /api/v1/feedback). На вкладке «Сравнение с Akismet» видно, кто чаще называл настоящую заявку спамом и кто чаще пропускал спам.
Когда Защита ошибается не чаще Akismet — включите боевой режим и отключите Akismet.

Вместе с другими скриптами ДАРА

На одной странице могут стоять скрипты нескольких продуктов ДАРА и продуктов, построенных на них. Они договариваются через общее ядро window.__dc:

проверка визита и капча — одни на визит: прошёл капчу один раз — её не покажет и другой скрипт;
каждым счётчиком Метрики управляет тот, кто первым его взял, — визит не задвоится;
чужие cookie (dara_visitor ДАРА Отпечатка, _dara_a ДАРА Аналитики) только читаются и никогда не перезаписываются;
если скрипт Защиты вставлен дважды, работает только первый.

Если наш сервер недоступен

Скрипт ждёт ответа полторы секунды. Не дождался — формы уходят как обычно (без токена; API потом проверит их по содержимому), счётчики запускаются как обычно (кроме явных ботов по признакам браузера). Сбой на нашей стороне не должен ломать ваш сайт.

Данные и cookies

Скрипт Защиты не ставит cookie. Признаки браузера и сводка поведения уходят на наш сервер для оценки визита.
Визиты хранятся 30 дней, проверки заявок — 90 дней, данные форм в проверках — 30 дней в зашифрованном виде, и только у заявок с вердиктом «спам» или «подозрительно». Сервера — в России.
В политике конфиденциальности сайта упомяните, что сайт использует сервис защиты от ботов и спама ДАРА ЗАЩИТА.