Интеграция

Подключение SDK

Три способа интеграции — выберите подходящий для вашей ситуации.

Способ 1 — Декларативный режим (ноль JS)

Добавьте атрибут data-formhook к тегу <form> и подключите скрипт-loader. Loader найдёт форму, подключит капчу, перехватит submit и отправит данные — без единой строки JS с вашей стороны.

Атрибуты

АтрибутОбязательныйОписание
data-formhookдаМаркер для loader
data-sitekeyдаsiteKey сайта из дашборда
data-success-redirectнетURL для редиректа после успешной отправки
data-error-messageнетТекст ошибки при сбое отправки
html 
<form
  data-formhook
  data-sitekey="ВАШ_SITE_KEY"
  data-success-redirect="/thanks"
  data-error-message="Не удалось отправить, попробуйте ещё раз">

  <input name="name" placeholder="Имя" required />
  <input name="email" type="email" placeholder="Email" required />
  <textarea name="message" placeholder="Сообщение"></textarea>

  <!-- Место для виджета капчи (если включена) -->
  <div class="formhook-captcha"></div>

  <button type="submit">Отправить</button>
</form>

<script src="https://app.form-hook.com/sdk/v3/loader.min.js" async defer></script>

Способ 2 — Явный JS API (v3)

Для SPA, нестандартной UX или кастомных анимаций используйте window.formhook напрямую. SDK v3 регистрирует глобальный объект после загрузки — используйте formhook.ready(cb) для инициализации.

API объекта window.formhook

МетодОписание
ready(callback)Ждёт загрузку SDK, затем вызывает callback
render(selector, options)Рендерит виджет капчи. Возвращает widgetId
isSolved(widgetId)Возвращает true если капча решена
submit(widgetId, data)Отправляет заявку. Возвращает Promise, при ошибке бросает с err.code
reset(widgetId)Сбрасывает капчу после ошибки или успешной отправки
remove(widgetId)Уничтожает виджет капчи (при размонтировании компонента)

Параметры render()

ПараметрТипОписание
sitekeystringsiteKey сайта
locale"ru" | "en"Язык виджета капчи
themestringlight, dark, dark-blue, dark-red, coffee, auto
callbackfunctionВызывается после успешного решения капчи
expired-callbackfunctionВызывается при истечении капчи
error-callbackfunctionВызывается при ошибке. Аргумент: { code, message }
html 
<div id="captcha-container"></div>
<button id="send" disabled>Отправить</button>

<script src="https://app.form-hook.com/sdk/v3/loader.min.js" async defer></script>
<script>
  var widgetId = null;

  window.formhook.ready(function() {
    widgetId = window.formhook.render('#captcha-container', {
      sitekey: 'ВАШ_SITE_KEY',
      locale: 'ru',
      theme: 'auto',
      callback: function() {
        document.getElementById('send').disabled = false;
      },
      'expired-callback': function() {
        document.getElementById('send').disabled = true;
      },
      'error-callback': function(err) {
        console.error('captcha error:', err.code, err.message);
      },
    });
  });

  document.getElementById('send').addEventListener('click', async function() {
    if (!widgetId || !window.formhook.isSolved(widgetId)) {
      alert('Пожалуйста, решите капчу');
      return;
    }

    try {
      const result = await window.formhook.submit(widgetId, {
        name: document.getElementById('name').value,
        email: document.getElementById('email').value,
      });
      console.log('Заявка отправлена:', result.id);
      window.formhook.reset(widgetId); // сбросить капчу после успеха
    } catch (err) {
      console.error(err.code, err.message);
      if (err.code === 'CAPTCHA_ANSWER_INVALID' || err.code === 'CAPTCHA_NOT_SOLVED') {
        window.formhook.reset(widgetId); // сбросить капчу при ошибке капчи
      }
    }
  });
</script>

Способ 3 — Прямой HTTP (без SDK)

Если SDK не нужен (серверная интеграция, curl, Postman) — отправляйте POST напрямую. Если на сайте включена капча, приложите captcha_challenge_id и captcha_answer.

bash 
curl -X POST https://app.form-hook.com/api/c1/sites/ВАШ_SITE_KEY/submissions \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Иван Петров",
      "email": "ivan@example.com",
      "message": "Хочу узнать подробнее"
    }
  }'

Ответ при успехе:

json 
{ "id": "01HXYZ..." }

С капчей:

json 
{
  "data": { "name": "Иван", "email": "ivan@example.com" },
  "captcha_challenge_id": "challenge-uuid",
  "captcha_answer": 42
}
При прямом POST без SDK капча не рендерится автоматически. Сначала получите challenge через POST /api/c1/sites/{siteKey}/captcha/challenges — см. API Reference.

Подключение loader на разных платформах

html 
<!-- HTML / статический сайт -->
<script src="https://app.form-hook.com/sdk/v3/loader.min.js" async defer></script>

<!-- Next.js / app router (layout.tsx) -->
<Script src="https://app.form-hook.com/sdk/v3/loader.min.js" strategy="afterInteractive" />

<!-- Tilda — в настройках сайта: "Скрипты в <head>" или "Перед </body>" -->
← Назад Быстрый старт Далее → Примеры кода