Автоматическое подключение через HTML-атрибуты

Автоматическое подключение — это способ добавить Servicepipe Widget CAPTCHA в форму на сайте, просто вставив в код страницы с формой нужный скрипт и контейнер с атрибутами.

Особенности подключения:

Капча постоянно размещена на странице. Пользователь видит её сразу, как только загрузил страницу.
Для создания виджета не нужно писать JavaScript-код.
Виджет настраивается через HTML-атрибуты.
Токен нужно отправить на бэкенд вместе с остальными полями формы.

Если вы хотите, чтобы капча появлялась на странице после действия пользователя или открывалась в модальном окне, используйте Расширенное подключение через JavaScript API.

Как работает эта интеграция:

Вы подключаете скрипт Servicepipe Widget CAPTCHA и добавляете на страницу HTML-элемент с нужными атрибутами. SDK сам находит этот элемент и отрисовывает в нём виджет.
Загрузив страницу, пользователь видит на ней виджет с чекбоксом «Я не робот» внутри.
Пользователь устанавливает флажок в чекбокс.
Открывается модальное окно, Servicepipe рассчитывает bot score пользователя.

Если bot score низкий, модальное окно закрывается автоматически, а внутри виджета появляется надпись «✅ Проверено».

Если bot score выше порогового значения, в модальном окне появляется задание капчи.
Пользователь пытается пройти капчу.

Если прошёл неуспешно или поведение было похоже на бота, он получает новое задание. Новая капча может выдаваться бесконечно — это ловушка для ботов, которая заставляет их снова и снова тратить ресурсы на решение, не допуская до защищаемого действия.

Если прошёл успешно, модальное окно закрывается, а внутри виджета появляется сообщение «✅ Проверено». Параллельно с этим Servicepipe присылает в браузер токен, который свидетельствует, что капча пройдена человеком.
Когда пользователь отправляет форму, токен уходит на ваш бэкенд вместе с остальными полями этой формы.
Ваш бэкенд обращается к Servicepipe, чтобы проверить полученный токен. Если с токеном всё в порядке, можно обработать форму. Если токен не прошёл проверку, форму лучше отбросить — скорее всего, её отправил злоумышленник.

Следуя шагам ниже, вы подключите Servicepipe Widget CAPTCHA к странице сайта, настроите обработку полученных токенов на бэкенде и протестируете интеграцию.

При работе вам могут пригодиться две статьи из справочника по интеграции: Ошибки виджета в браузере, Ошибки при серверной проверке токена. Откройте их в новой вкладке, чтобы нужная информация всегда была под рукой.

1. Получите `SiteKey` и `ApiKey`

Мы передадим вам два значения:

SiteKey — публичный ключ виджета. На следующих шагах вы добавите его в HTML-код страницы, чтобы SDK узнал ваш сайт и отдал нужную конфигурацию капчи. SiteKey будет виден в исходном коде HTML и не является секретом.

У вас может быть несколько SiteKey. Так бывает, если вы запросили несколько разных конфигураций капчи: например, одну менее сложную для страницы входа и одну более сложную — для страницы регистрации. У каждой конфигурации будет свой SiteKey.

ApiKey — приватный серверный ключ. Ваш бэкенд использует его, когда обращается к API Servicepipe, чтобы проверить токен пользователя. По этому ключу наша система узнает вас как клиента и выдаст результат проверки.

ApiKey является секретом. Храните его только на бэкенде и не добавляйте его в HTML-код, JavaScript-код страницы и другие файлы, которые загружаются в браузер пользователя.

2. Подключите JavaScript-скрипт на страницу

Добавьте скрипт Servicepipe Widget CAPTCHA в тег <head> на странице, где должен появиться виджет:

<script src="https://captcha.servicepipe.tech/captcha.js" async defer></script>

Если на вашем сайте используется Content Security Policy, браузер может заблокировать загрузку скрипта или iframe с капчей. В этом случае добавьте домен https://captcha.servicepipe.tech в правила script-src и frame-src.

Что делает этот скрипт: при каждой загрузке страницы он ищет элемент с классом sp-captcha и создаёт внутри виджет с капчей. Элемент sp-captcha вы добавите в код страницы на следующем шаге.

3. Добавьте контейнер капчи на страницу

Вставьте на страницу элемент <div> с классом sp-captcha в том месте, где должна появиться капча. Укажите у него нужные опции через HTML-атрибуты:

Атрибут Значение Что делает Обязателен

Атрибут	Значение	Что делает	Обязателен
`class`	`sp-captcha`	Помечает элемент как контейнер капчи. По этому классу SDK находит место на странице, куда встроить виджет.	Да
`data-sitekey`	Значение `SiteKey`, полученное вами от Servicepipe, например, `O4FUxStKtioH1seP`	Передаёт публичный ключ виджета. По этому ключу Servicepipe определяет, к какой интеграции относится виджет и какие настройки капчи нужно применить.	Да
`data-language`	`ru` или `en`. По умолчанию: `ru`	Задаёт язык интерфейса капчи. Доступны два значения: `ru` (русский) и `en` (английский). Если атрибут не указан, капча будет на русском.	Нет
`data-response-field`	Без значения. Наличие атрибута включает эту возможность	Создаёт скрытое поле для токена внутри HTML-элемента виджета. Если пользователь успешно пройдёт капчу, SDK запишет токен в это поле.	Да (но вместо него можно использовать `data-callback`)
`data-response-field-name`	Имя поля, например `sp-captcha-token`. По умолчанию: `captcha-token`	Задаёт имя скрытого поля с токеном, которое вы включили через `data-response-field`. Если этот атрибут не указан, SDK создаст поле с именем по умолчанию — `captcha-token`.	Нет
`data-callback`	Имя вашей глобальной функции, например, `onCaptchaSuccess`	Задаёт имя функции, которую SDK вызовет, если капча пройдена успешно. В эту функцию SDK передаст токен. Функцию вы напишете на шаге 4.	Да (но вместо него можно использовать `data-response-field`)
`data-error-callback`	Имя вашей глобальной функции, например `onCaptchaError`	Задаёт имя функции, которую SDK вызовет, если при работе виджета возникнет ошибка в браузере. В эту функцию SDK передаст объект ошибки с `error.code` и `error.message`. Функцию вы напишете на шаге 4.	Нет
`data-expired-callback`	Имя глобальной функции, например `onCaptchaExpired`	Задаёт имя функции, которую SDK вызовет, когда срок действия уже полученного токена истечёт. Функцию вы напишете на шаге 4.	Нет

class

sp-captcha

Помечает элемент как контейнер капчи. По этому классу SDK находит место на странице, куда встроить виджет.

Да

data-sitekey

Значение SiteKey, полученное вами от Servicepipe, например, O4FUxStKtioH1seP

Передаёт публичный ключ виджета. По этому ключу Servicepipe определяет, к какой интеграции относится виджет и какие настройки капчи нужно применить.

Да

data-language

ru или en. По умолчанию: ru

Задаёт язык интерфейса капчи. Доступны два значения: ru (русский) и en (английский).

Если атрибут не указан, капча будет на русском.

Нет

data-response-field

Без значения. Наличие атрибута включает эту возможность

Создаёт скрытое поле для токена внутри HTML-элемента виджета.

Если пользователь успешно пройдёт капчу, SDK запишет токен в это поле.

Да (но вместо него можно использовать data-callback)

data-response-field-name

Имя поля, например sp-captcha-token.

По умолчанию: captcha-token

Задаёт имя скрытого поля с токеном, которое вы включили через data-response-field.

Если этот атрибут не указан, SDK создаст поле с именем по умолчанию — captcha-token.

Нет

data-callback

Имя вашей глобальной функции, например, onCaptchaSuccess

Задаёт имя функции, которую SDK вызовет, если капча пройдена успешно. В эту функцию SDK передаст токен.

Функцию вы напишете на шаге 4.

Да (но вместо него можно использовать data-response-field)

data-error-callback

Имя вашей глобальной функции, например onCaptchaError

Задаёт имя функции, которую SDK вызовет, если при работе виджета возникнет ошибка в браузере. В эту функцию SDK передаст объект ошибки с error.code и error.message.

Функцию вы напишете на шаге 4.

Нет

data-expired-callback

Имя глобальной функции, например onCaptchaExpired

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

Функцию вы напишете на шаге 4.

Нет

Например, так может выглядеть подключение виджета к форме регистрации:

<form action="/signup" method="post">
  <input type="email" name="email">
  <input type="password" name="password">
  <div
    class="sp-captcha"
    data-sitekey="<SITE_KEY>"
    data-language="ru"
    data-response-field
    data-response-field-name="sp-captcha-token"
  ></div>
  <button type="submit">Зарегистрироваться</button>
</form>

В этом примере <SITE_KEY> — это значение, которое мы передали вам на шаге 1. Когда пользователь пройдёт капчу, SDK создаст скрытое поле sp-captcha-token и запишет токен туда. При отправке формы этот токен уйдёт на ваш бэкенд вместе с остальными полями формы.

4. Добавьте callback-функции (опционально)

Если на шаге 3 вы добавили атрибуты с callback-функциями, опишите в коде сайта функции с такими же именами. Эти функции должны быть в глобальной области видимости.

Например, вы указали у виджета такие атрибуты:

data-error-callback="onCaptchaError"
data-expired-callback="onCaptchaExpired"

Предположим, на странице есть элемент для сообщения пользователю с id="captcha-status". Добавьте callback-функции:

<script>
  window.onCaptchaError = function(error) {
    console.error("CAPTCHA error:", error.code, error.message);

    document.querySelector("#captcha-status").textContent =
      "Не удалось загрузить капчу. Обновите страницу и попробуйте ещё раз.";

    fetch("/analytics/captcha-error", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        code: error.code,
        message: error.message
      })
    });
  };

  window.onCaptchaExpired = function() {
    document.querySelector("#captcha-status").textContent =
      "Пройдите капчу ещё раз.";
  };
</script>

Функция onCaptchaError получит объект ошибки с error.code и error.message (возможные ошибки виджета и сообщения смотрите в справочнике по интеграции). В примере она логирует ошибку, показывает сообщение пользователю и отправляет информацию об ошибке в аналитику.

Функция onCaptchaExpired вызовется, когда срок действия токена истечёт. SDK автоматически очистит скрытое поле с истёкшим токеном, а функция попросит пользователя пройти капчу ещё раз.

5. Примите токен на бэкенде

Настройте бэкенд так, чтобы он получал токен из запроса вместе с остальными данными формы.

Имя поля зависит от настройки data-response-field-name:

Если вы указали data-response-field-name="sp-captcha-token", SDK создаст скрытое поле с именем sp-captcha-token и запишет в него токен.
Если вы добавили data-response-field, но не указали data-response-field-name, токен придёт в поле со стандартным именем captcha-token.

После отправки формы бэкенд должен прочитать значение соответствующего поля. Если поле отсутствует или токен пуст, не выполняйте защищаемое действие. Полученный токен обязательно проверьте через серверный API, как описано на следующем шаге.

6. Проверьте токен через серверный API

Серверная проверка подтверждает, что пользователь действительно прошёл капчу и получил токен от Servicepipe. Она защищает от злоумышленников, которые подставляют в поле токена произвольное значение в надежде, что бэкенд проверяет только его наличие.

В ходе проверки Servicepipe удостоверится, что:

токен выдан сервисом Servicepipe;
токен относится к вашему SiteKey;
срок действия токена не истёк;
токен не был использован повторно.

Чтобы проверить токен, отправьте с бэкенда такой запрос:

curl -H "X-Api-Key: <API_KEY>" \
  "https://captcha.servicepipe.tech/<SITE_KEY>/verify?jwt=<TOKEN>"

Замените значения:

<API_KEY> — на приватный ключ, который мы передали вам на шаге 1;
<SITE_KEY> — на публичный ключ виджета, который мы передали вам на шаге 1;
<TOKEN> — на токен, который получил ваш бэкенд.

Если ваш бэкенд может определить IP пользователя, также передайте его в параметре ip:

curl -H "X-Api-Key: <API_KEY>" \
  "https://captcha.servicepipe.tech/<SITE_KEY>/verify?jwt=<TOKEN>&ip=<USER_IP>"

Параметр ip необязательный, но рекомендуем передавать его, если это возможно. Если капчу прошли в одном окружении, а токен используют в другом (так часто работают фермы по прохождению капчи), параметр IP поможет это выявить. В этом случае наша система покажет, что проверка токена провалена, и вы не допустите злоумышленника до защищаемого действия.

7. Обработайте ответ проверки

Если токен прошёл проверку, Servicepipe вернёт ответ с success: true:

{
  "success": true,
  "request_id": "...",
  "site_key": "<SITE_KEY>"
}

Это значит, всё в порядке — капчу правда решил человек. В этом случае продолжайте обработку защищаемого действия. Например, если капча защищала страницу входа в ваш сервис, можно дать пользователю войти.

Если токен не прошёл проверку, Servicepipe вернёт success: false и поле error — объяснение, что было не так. Также может вернуть дополнительные диагностические поля, например, validation_check — информацию, истёк срок действия токена или ещё нет на момент проверки.

Пример такого ответа:

{
  "success": false,
  "error": "invalid_jwt",
  "validation_check": "expired"
}

Список возможных значений error

Значение поля error Описание

Значение поля `error`	Описание
`missing_required_params`	Отсутствуют обязательные параметры. Например, не передан `jwt` в query-параметре.
`invalid_jwt`	Токен не прошёл проверку. Например, токен повреждён, просрочен, уже использован повторно или содержит некорректные `iat` или `exp`.
`invalid_jwt_request_id`	В JWT отсутствует или пустой `requestId`. Например, claim `requestId` не передан.
`invalid_jwt_site_key`	В JWT отсутствует или пустой `siteKey`. Например, claim `siteKey` не передан.
`path_mismatch`	`siteKey` из JWT не соответствует пути запроса `/{site_key}/verify`. Например, JWT предназначен для другого `site_key`.
`storage_error`	Временная ошибка серверного хранилища.

missing_required_params

Отсутствуют обязательные параметры. Например, не передан jwt в query-параметре.

invalid_jwt

Токен не прошёл проверку. Например, токен повреждён, просрочен, уже использован повторно или содержит некорректные iat или exp.

invalid_jwt_request_id

В JWT отсутствует или пустой requestId. Например, claim requestId не передан.

invalid_jwt_site_key

В JWT отсутствует или пустой siteKey. Например, claim siteKey не передан.

path_mismatch

siteKey из JWT не соответствует пути запроса /{site_key}/verify. Например, JWT предназначен для другого site_key.

storage_error

Временная ошибка серверного хранилища.

При success: false, не выполняйте защищаемое действие автоматически.

Если токен повреждён, просрочен, уже использован или содержит некорректные iat или exp, попросите пользователя пройти капчу повторно и отправьте новый токен на проверку.

Ошибки missing_required_params, invalid_jwt_request_id, invalid_jwt_site_key и path_mismatch могут указывать на неправильную настройку интеграции или некорректно сформированный запрос. Повторное прохождение капчи обычно их не устранит. Запишите ошибку в журнал и проверьте обязательные параметры, передаваемый токен и соответствие SiteKey в URL и токене.

Отдельный случай: результат проверки не удалось получить из-за временной ошибки Servicepipe. К таким ситуациям относятся storage_error, недоступность API, тайм-аут, сетевая ошибка или ответ HTTP 5xx. Повторное прохождение капчи не устранит причину ошибки. В этом случае можно использовать один из двух подходов:

Fail-closed: не выполнять защищаемое действие, пока токен не удастся проверить. Этот подход обеспечивает более строгую защиту и подходит для атакуемых или дорогостоящих операций, например отправки SMS или регистрации аккаунта.
Fail-open: разрешить защищаемое действие без подтверждённого результата проверки, если API временно недоступен. Этот подход сохраняет доступность сервиса, но снижает защиту от ботов. Используйте его только там, где такой риск допустим.

8. Проверьте интеграцию

Настройка закончена. Теперь рекомендуем пройти весь сценарий на тестовой странице:

Откройте страницу, где подключён виджет.
Убедитесь, что виджет капчи появился в нужном месте страницы.
Выполните защищаемое действие. Например, если вы проверяете сценарий с формой, заполните поля формы и пройдите капчу.
Проверьте, что бэкенд получил токен.
Проверьте, что бэкенд отправил токен в Servicepipe и получил success: true.
Убедитесь, что защищаемое действие выполняется только после успешной серверной проверки.

Если виджет не появился, проверьте, что:

скрипт загружается без ошибок,
значение data-sitekey указано верно,
правила Content Security Policy не блокируют домен https://captcha.servicepipe.tech.

9. Интеграция закончена

Поздравляем, вы подключили Servicepipe Widget CAPTCHA! Теперь важные действия в вашем сервисе надёжно защищены от ботов.

Автоматическое подключение через HTML-атрибуты

1. Получите SiteKey и ApiKey

2. Подключите JavaScript-скрипт на страницу

3. Добавьте контейнер капчи на страницу

4. Добавьте callback-функции (опционально)

5. Примите токен на бэкенде

6. Проверьте токен через серверный API

7. Обработайте ответ проверки

8. Проверьте интеграцию

9. Интеграция закончена

1. Получите `SiteKey` и `ApiKey`