Встраивания

Встраивания позволяют разместить форму SupDesk прямо на вашем собственном сайте. Посетители записываются в список ожидания, пишут вам или регистрируются в бета- программе, не покидая ваш сайт.

Нужен пузырёк чата, а не форма? У онлайн-чата свой загрузчик (chat.js) и свой фрагмент кода — см. Онлайн-чат.

Встроить можно три формы:

Форма	Что делает	Требуется
`waitlist`	Собирает записи в список ожидания	Список ожидания включён
`contact`	Открывает переписку во входящих проекта	Личные сообщения Pro
`beta`	Публичная запись в одну бета-программу	Бета включена, программа активна с публичной записью

Как добавить встраивание

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

Список ожидания — раздел Список ожидания проекта, под карточкой настроек
Обратная связь — страница Настройки проекта, раздел Встроить форму обратной связи
Бета — страница бета-программы, раздел Встраивание

Фрагмент выглядит так:


<script src="https://acme.supdesk.app/embed.js"
        data-supdesk="contact"
        data-title="Написать в Acme" data-height="520" async></script>
<noscript>
  <iframe src="https://acme.supdesk.app/embed/contact" width="100%" height="520"
          style="border:0" title="Написать в Acme"></iframe>
</noscript>

Скрипт вставляет форму там, где стоит тег, и меняет её высоту вслед за содержимым — например, когда появляются ошибки проверки или когда после отправки форма сворачивается в короткое подтверждение. Блок <noscript> — это обычный iframe, поэтому форма работает и у посетителей с отключённым JavaScript.

Всё отдаётся с вашего собственного домена портала. Если у вас есть собственный домен, консоль выдаёт фрагменты на нём; иначе используется ваш поддомен *.supdesk.app.

Собственные домены и корневые домены

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

Следить стоит за фрагментом, скопированным до добавления собственного домена. Запросы к вашему прежнему источнику перенаправляются на собственный домен, и загрузчик принимает это перенаправление, только если у них общий корневой домен — например, поддомен портала feedback.apibot.dev и собственный домен www.apibot.dev живут оба на apibot.dev. Если ваш собственный домен находится на другой корневой зоне, перенаправление между доменами не сработает: скопируйте фрагмент из консоли заново, когда собственный домен станет активным.

Атрибуты

Атрибут	Обязательный	Описание
`data-supdesk`	да	Какую форму встроить: `waitlist`, `contact` или `beta`
`data-program`	только для беты	Слаг бета-программы
`data-title`	нет	Доступное название фрейма. По умолчанию `SupDesk form`
`data-height`	нет	Начальная высота в пикселях до первой подстройки. По умолчанию `360`
`data-ref`	нет	Реферальный код списка ожидания, которому засчитать запись

На одной странице можно разместить несколько встраиваний — дайте каждому свой тег <script>.

Content Security Policy

Если ваш сайт отправляет заголовок Content-Security-Policy, разрешите источник вашего портала в двух директивах, иначе браузер заблокирует встраивание:


script-src https://acme.supdesk.app;
frame-src  https://acme.supdesk.app;

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

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

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

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

Приватность и вход

Встроенные формы никогда не читают и не записывают сессию портала — браузеры по своему устройству не отправляют такие cookie во фрейм на чужой странице. Вместо этого каждое встраивание работает начиная с email: посетитель указывает адрес и получает ссылку письмом.

Из этого следует одна особенность, о которой стоит знать, размещая встраивание: посетитель завершает сценарий в обычной вкладке браузера, а не внутри вашей страницы.

Список ожидания — запись фиксируется сразу; в письме приходят позиция и персональная реферальная ссылка
Бета — в письме приходит ссылка подтверждения, которая записывает участника
Обратная связь — сообщение сразу попадает в ваши входящие; письмо служит подтверждением и позволяет прочитать ваши ответы

Записи списка ожидания, созданные через встраивание, сохраняются с источником embed, поэтому в таблице записей и в CSV-экспорте их можно отличить от записей с портала.

Что видят посетители

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

Встроенные страницы не индексируются поисковыми системами; каноническими и индексируемыми версиями остаются публичные страницы портала.

Старый фрагмент списка ожидания

До появления скрипта-загрузчика встраивание списка ожидания было простым iframe на /waitlist/embed:


<iframe src="https://acme.supdesk.app/waitlist/embed" width="100%" height="360"
        style="border:0" title="Список ожидания"></iframe>

Он продолжает работать — менять ничего не нужно. Переход на текущий фрагмент даёт автоматическую подстройку высоты; фиксированная height старого iframe — его единственный реальный недостаток.