Поймать плохую отправку до «Отправить» с помощью предпроверки

Отклонённая отправка стоит того единственного, что этот продукт не может вернуть: человек был на странице и перестал. FormFlow хранит каждый отказ как запись, с которой можно что-то сделать, а сигналы здоровья формы их считают. Предпроверка — единственная часть этого решения, которая выполняется до «Отправить». Она появилась в v1.0.0.

Что отвечает предпроверка

Отправьте POST на /api/v1/f/{token}/preflight с теми ответами, которые отправила бы ваша форма, в формате JSON, и публичным токеном формы в пути. Конечная точка возвращает решение, которое вынесла бы точка приёма по этим ответам, не вынося его. Передайте собственный заголовок Origin страницы, и он будет проверен ровно так, как его проверяет точка отправки. Контракт описан в справочнике API.

В ответе четыре ключа: ok, errors, checked и policy. errors — это объект, где ключи — имена полей, а значения — списки предложений; он остаётся объектом даже пустым, чтобы сгенерированный вызывающий код мог обращаться по индексу. checked называет, что именно было спрошено — структура, origin и схема; на размещённой странице origin отсутствует, потому что страница, которую отдаёт FormFlow, не подчиняется вашему списку разрешённых источников.

Вызовите её, пока человек ещё на странице

Одного fetch достаточно. Вот форма вызова; привяжите его к тому событию, которому ваша страница уже доверяет, например к уходу из поля.

const endpoint = 'https://formflow.digital/api/v1/f/YOUR_FORM_TOKEN/preflight'

async function preflight(answers) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
    body: JSON.stringify(answers),
  })

  // A 429 or an outage is not a verdict. Say nothing rather than something wrong.
  if (!response.ok) return null

  const { ok, errors, checked, policy } = await response.json()
  return ok ? [] : Object.entries(errors)
}

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

Прочитать ответ

Два ключа в errors — не поля. origin несёт отказ по списку разрешённых источников, а submission — отказ, который относится к форме целиком, а не к одному ответу, например к закрытой форме. Записывайте блок policy в журнал: версия и отпечаток вместе определяют ровно ту политику, по которой вынесено решение, и это именно то, что нужно в день, когда успех здесь сменяется отказом там.

Чего она не спрашивает

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

Но она внутри ограничителя частоты. Предпроверка делит корзину token|IP и корзину запросов всей команды с точкой отправки, поэтому всплеск может вернуть 429 с Retry-After. 429 — это отсутствие решения, а не отказ, и страница должна молчать, а не выдумывать ошибку.

Где она стоит

Все остальные механизмы FormFlow для отклонённой отправки работают после того, как человека отклонили: реестр отказов, сигнал здоровья, поверхность отказов и папка восстановления. Эта — единственная, что работает до. Используйте её как первое из двух решений, но никогда как единственное.

• Успех — не обещание. Решает POST, и решает заново со всем тем, о чём предпроверка не спрашивала.

• Измените форму между двумя вызовами — и ответ может измениться вместе с ней. Версия политики в ответе — та, что судила вас.

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

• errors использует имена полей как ключи, но origin и submission — не поля; показывайте их вверху формы.

• Любой, у кого есть публичный токен формы, может её вызвать. Это ничего не доказывает о том, кто вызывает, и это не секрет.