# Формы

Форма, которую вы создаёте в панели, публикуете по собственной ссылке и встраиваете куда угодно. Каждая отправка приходит на телефон как push-уведомление — тот же путь доставки, что и у вебхука, поэтому маршрутизация, уровни приоритета и история сообщений работают так, как вы уже привыкли.

Без почтового ящика посередине. Без ручной проверки таблиц.

## Создание формы

**Формы → Создать.** Конструктор состоит из пяти вкладок и живого предпросмотра рядом с ними:

| Вкладка | Что здесь настраивается |
|---------|-------------------------|
| Поля | Заголовок, вводный текст, сами поля, текст в подвале |
| Оформление | Тема, цвета, шрифт, размер, скругление углов, кнопка отправки |
| Настройки | Заголовок push-уведомления, маршрутизация, приоритет, ограничения ответов, сообщения |
| Публикация | Публичная ссылка, QR-код, код для встраивания |
| Предпросмотр | Тот же живой предпросмотр, для узких экранов |

Сохраните форму, и на вкладке «Публикация» появится ссылка: `https://frms.click/<id>`.

## Типы полей

| Группа | Типы |
|--------|------|
| Текст | Короткий текст, длинный текст, email, телефон, число, URL, дата |
| Выбор | Выпадающий список, переключатели, флажки, одиночный флажок (согласие) |
| Оценка | Оценка звёздами (1–5), NPS (0–10) |
| Оформление | Заголовок, абзац, разделитель |
| Отслеживание | Скрытое поле |

До **30 полей** в одной форме, до 50 вариантов в поле выбора. Поля email, телефона, числа и URL проверяются в браузере и повторно на сервере — проверка в клиенте служит для удобства, а не для защиты.

Поля оформления носят декоративный характер: в сообщении они никогда не появляются. Загрузка файлов и платежи не поддерживаются.

### Скрытые поля

Скрытое поле переносит значение из ссылки в сообщение. Задайте имя параметра, и `?utm_source=newsletter` в URL попадёт в уведомление. Одним кликом можно добавить сразу все пять UTM-параметров.

Когда форма встроена, параметры **страницы-хоста** передаются дальше, поэтому посадочная страница кампании помечает свои отправки без дополнительной работы с вашей стороны.

## Как выглядит сообщение

Сначала идут ответы — в порядке следования полей:

```
Name: Jane Doe
Email: jane@example.com
Rating: ★★★★☆ 4/5
Message: Do you ship to Canada?

utm_source: newsletter
Form: Contact
IP: 203.0.113.10
Submitted: 2026-09-23 14:05
```

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

## Заголовок push-уведомления

По умолчанию уведомление называется `Form: <form name>`. Шаблон делает его полезным с первого взгляда:

```
New lead: {Name} ({Email})
```

Подстановки ссылаются на поля **по их подписи**, без учёта регистра, а также `{form}` — название формы. Пустые ответы пропускаются в заголовке; если ничего не осталось, используется заголовок по умолчанию. Шаблон никогда не показывается на публичной странице.

## Значок Pocket Alert

Опубликованная форма содержит небольшую ссылку «Работает на Pocket Alert» под собой. На платном тарифе её можно отключить в **Оформление → Брендинг**.

Решение принимает API, а не браузер: сохранение этого флага на бесплатном тарифе сбрасывает его, а если платный тариф заканчивается, значок снова появляется на публичной странице без каких-либо действий с вашей стороны.

## Маршрутизация и приоритет

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

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

## Закрытие формы

Три независимых переключателя, любой из которых закрывает форму:

- **Приём ответов** — выключение закрывает форму сразу
- **Лимит ответов** — закрывает форму после N отправок; место резервируется до создания сообщения, поэтому всплеск трафика не может его превысить
- **Закрыть в** — дата и время в вашем часовом поясе

Закрытая форма по-прежнему открывается: посетители видят ваше сообщение о закрытии вместо полей, а отправки отклоняются на сервере.

## Встраивание

На вкладке «Публикация» есть код для встраивания через скрипт:

```html
<div data-pocketalert-form="<id>"></div>
<script src="https://frms.click/embed/form.js" async></script>
```

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

После отправки контейнер генерирует событие `pocketalert:submit`, к которому можно подключить аналитику:

```js
document.querySelector('[data-pocketalert-form]')
  .addEventListener('pocketalert:submit', () => gtag('event', 'generate_lead'));
```

Там, где скрипты не разрешены, также предоставляется простой фрагмент с `<iframe>` — с фиксированной высотой, и параметры URL в нём не передаются.

## Ограничение мест использования формы

Идентификатор формы публичный — он передаётся в ссылке и QR-коде, поэтому по умолчанию любой, кто его знает, может встроить форму на любую страницу. **Настройки → Где можно использовать** позволяет задать список доменов и закрыть эту возможность:

- встраивать форму могут только эти сайты (страница отдаётся с соответствующей политикой `frame-ancestors`);
- отправка, у которой `Origin` (или `Referer`) не входит в список, отклоняется с ответом `403`;
- ссылка на саму форму продолжает работать в любом случае.

Указывайте хосты, а не URL: `example.com`, `app.example.com`, `*.example.com` для всех поддоменов, `localhost:3000` во время разработки. Допускается до 10 записей. `www.` игнорируется, поэтому `example.com` охватывает и `www.example.com`.

Пустой список означает «где угодно» — это подходящая настройка для ссылки, которую вы публикуете в описании профиля или для QR-кода на плакате.

> **Warning: Что это защищает, а что нет**
>
> `Origin` выставляет браузер, и страница не может подделать его. Скрипт, который обращается к API напрямую, может отправить любой заголовок, поэтому список разрешённых доменов не даёт встроить вашу форму на чужой сайт, но не защищает от целенаправленного флуда. От такого случая защищают ограничения частоты, описанные ниже.

## Откуда пришла отправка

Когда отправка приходит из встроенной формы, в сообщение рядом с IP записывается хост:

```
Form: Contact (abc123)
Source: shop.example.com
IP: 203.0.113.10
```

У отправок со страницы самой формы строки `Source` нет.

## Защита от спама

- Поле-ловушка (honeypot), которое человек никогда не видит. Боты, заполнившие его, получают обычный экран успеха, а сообщение не доставляется.
- Ограничения частоты: 10 отправок в минуту с одного IP, 60 в минуту и 300 в час на форму. Часовой лимит нужен, чтобы флуд не выжег дневной запас сообщений за несколько минут.
- Публичные страницы форм имеют `noindex`, поэтому сама по себе форма не появляется в результатах поиска.

CAPTCHA пока не требуется и в формах не предлагается.

## Лимиты тарифов

| Тариф | Формы |
|-------|-------|
| Бесплатный | 1 |
| Starter | 10 |
| Medium | 30 |
| Large | Без ограничений |

Сами отправки ограничены только вашим дневным лимитом сообщений.

## API

Всё, что делает конструктор, доступно через REST API:

| Эндпоинт | Что делает |
|----------|------------|
| [`GET /v1/forms`](https://info.pocketalert.app/api/forms/get-forms.md) | Список ваших форм |
| [`POST /v1/forms`](https://info.pocketalert.app/api/forms/create.md) | Создать форму |
| [`PUT /v1/forms/:tid`](https://info.pocketalert.app/api/forms/update.md) | Заменить её поля, оформление и настройки |
| [`DELETE /v1/forms/:tid`](https://info.pocketalert.app/api/forms/delete.md) | Удалить форму |
| [`GET /v1/forms/:tid`](https://info.pocketalert.app/api/forms/get-form.md) | Публичный: поля и оформление действующей формы |
| [`POST /v1/forms/:tid/submit`](https://info.pocketalert.app/api/forms/submit.md) | Публичный: принять отправку |

Первые четыре запроса используют ваш обычный токен; последние два вызывает сама страница формы.
