База знаний GetMyBot

Виджет на сайте

Настройте, установите, проверьте и диагностируйте виджет GetMyBot, и что происходит при всплеске новых посетителей.

На этой странице

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

Выберите пресет

В разделе «Виджет» начните с пресета «Онлайн-школа» или «Интернет-магазин». Пресет копирует редактируемые значения в текущую конфигурацию, а его будущие изменения не переписывают опубликованные настройки. Применение может заменить текущие правки, поэтому сначала проверьте изменения.

Что можно настроить

Студия виджета разбита на семь вкладок: «Поведение», «Приветствие и автоответы», «Рабочее время», «Контакты и приватность», «Диалоги», «Внешний вид» и «Установка». На них настраиваются бренд, кнопка запуска, панель, приветствие, тизер, видимость по адресам, уведомления посетителю, быстрые действия, форма перед чатом, рабочее время и поведение. Полное описание каждого поля на каждой вкладке – в «Настройках виджета». Быстрые действия безопасно отправляют в диалог настроенный текст и требуют подходящих реакций, чтобы посетитель получил полезный автоматический ответ.

Форма может собирать имя, email, телефон или номер заказа. Email и телефон лишь неподтверждённо дополняют профиль: они не подтверждают личность, не объединяют людей и не создают согласие на маркетинговые рассылки. Рабочие часы используют часовой пояс, недельные интервалы и исключения. Они описывают расписание, а не присутствие оператора в реальном времени.

Короткое приглашение рядом с кнопкой можно расположить сбоку от неё или над ней.

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

Предпросмотр перед публикацией

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

Разрешённые origin

Добавьте точные origin сайтов, на которых разрешено запускать виджет. Origin состоит из схемы, хоста и нестандартного порта, без пути:

https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000

Сопоставление точное. Подстановочных знаков нет: варианты с www и без него, http и https, а также разные поддомены: это разные origin. Для рабочего сайта нужен HTTPS. HTTP loopback допустим только для локальной разработки. Если текущий origin не сохранён, инициализация будет отклонена.

Этот список ограничивает встраивание в браузере. Он не заменяет авторизацию на сервере или защиту от злоупотреблений.

Установите фрагмент кода

Откройте «Виджет» → «Установка», скопируйте весь фрагмент и добавьте его один раз в общий шаблон каждой страницы, где нужен виджет, лучше перед </body>:

<script>
  window.mybot = window.mybot || {}; window.mybot.key = "eu-1a2b3c4d-...";
</script>
<script async src="https://getmybot.dev/loader.js"></script>

Присваивание ключа должно идти до загрузчика, а async нужно сохранить. Не разделяйте фрагмент. Дублировать его не нужно, но и не страшно: виджет монтируется один раз, а window.mybot = window.mybot || {} не затирает уже установленные track/identify. Подойдёт поле footer-скриптов CMS или контейнер диспетчера тегов, если он подключается один раз на странице.

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

Автоматическая диагностика

Выберите сохранённый разрешённый origin и адрес страницы на нём, затем запустите «Проверить установку». Диагностика сначала изучает статические признаки: доступность, полученный HTML, наличие канонического загрузчика, настройку ключа и возможные признаки CSP. Она не выполняет JavaScript, поэтому при установке через диспетчер тегов или SPA результат может быть неопределённым.

Затем диагностика открывает настоящую страницу и ждёт сигналы загрузчика, пакета виджета, инициализации и смонтированного виджета. Только статус готовности виджета подтверждает успешную установку. Тайм-аут означает, что сигнал среды выполнения не получен. У него может быть несколько причин, и это не однозначная диагностика CSP, сети или загрузчика.

CSP, диспетчеры тегов и блокировщики

Если на сайте настроен Content Security Policy, разрешите указанному рядом с фрагментом хосту загружать скрипты и выполнять сетевые запросы виджета. Возможности CSP зависят от браузера, поэтому статические признаки могут остаться неопределёнными. Сопоставляйте результат выполнения с консолью браузера.

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

Посетители, черновики и история

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

Виджет изолирован от страницы в закрытом Shadow DOM. Его стили не попадают на сайт, а CSS сайта не меняет виджет. Контейнер не перехватывает клики по странице вне кнопки запуска и панели.

Всплеск новых посетителей

У появления нового посетителя есть ограничение по скорости, отдельное на каждый аккаунт: примерно два новых посетителя в секунду в среднем, с запасом на всплеск около 500 подряд. Обычному сайту этого хватает с большим избытком: речь о порядке 170 000 новых посетителей в сутки.

Если запас исчерпан, инициализация виджета для нового посетителя отвечает 429 с заголовком Retry-After: 60, и виджет пробует снова позже. Уже известные посетители не затрагиваются: их диалоги, история и ответы операторов продолжают работать как обычно. Ограничение сознательно устроено так, чтобы всплеск замедлял приток новых собеседников, а не выключал общение с теми, кто уже пишет.

Почему ограничение на аккаунт, а не на IP-адрес: появление посетителя: единственное действие анонимного браузера, которое создаёт у вас реальную работу и расходует ваш лимит уникальных посетителей. Тот, кто хочет накрутить его, легко меняет IP-адреса, а счёт приходит вам. См. Тарифы про подсчёт уникальных посетителей.

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

Связывание посетителя с вашим пользователем

Когда посетитель авторизован на вашем сайте, дождитесь доступности mybot.identify() и только затем вызывайте его. Загрузчик и пакет виджета работают асинхронно, а очереди команд до загрузки нет. Запускайте этот код после того, как станет известен авторизованный пользователь вашего сайта:

async function identifySignedInVisitor() {
  const deadline = Date.now() + 3_000;

  while (Date.now() < deadline) {
    const identify = window.mybot?.identify;
    if (typeof identify === "function") {
      identify(async (visitorId) => {
        const response = await fetch("/mybot-sign", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ userId: currentUser.id, visitorId }),
        });
        return response.json(); // { userId, signature, expiresAt }
      });
      return;
    }
    await new Promise((resolve) => window.setTimeout(resolve, 50));
  }

  console.warn("GetMyBot identify() не готов; посетитель останется анонимным.");
}

void identifySignedInVisitor();

Код опрашивает API не больше трёх секунд, затем останавливается, а не вызывает отсутствующий API и не повторяет попытки бесконечно. При тайм-ауте, ошибке функции или подписи посетитель продолжит общаться анонимно. Функция получает асинхронно созданный visitorId. Передавайте его только на свой авторизованный сервер, не логируйте, не пересылайте и не добавляйте в клиентскую аналитику. Сервер возвращает { userId, signature, expiresAt } и вычисляет подпись, но не браузер:

signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)

Разделители: настоящие переводы строки. expiresAt: Unix-время в секундах: оно не должно быть в прошлом и не может быть больше чем на 24 часа вперёд. Привязывайте подпись к конкретному посетителю и создавайте её непосредственно перед возвратом.

Показ и смена секрета

Секрет identify() появляется в настройках виджета после подключения веб-канала. Показ не делает секрет недействительным. Показывайте его только когда он нужен серверу, затем убирайте с экрана и очищайте буфер обмена вручную: платформа не может надёжно очистить буфер браузера.

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

Поп-апы и формы заявок

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

Галерея шаблонов даёт готовую заготовку: по одной на каждую раскладку плюс Сбор заявок (большой блок с полем email, флажком согласия и кнопкой отправки) и Приглашение в чат (небольшой блок с кнопкой «открыть чат»).

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

Таргетинг сужает, когда поп-ап появляется. Группы правил объединяются по «И»: посетитель должен одновременно подходить по страницам, поведению, аудитории и устройству.

  • Страницы. До 20 шаблонов включения и 20 исключения. Шаблон: абсолютная ссылка http(s), точная или заканчивающаяся одной * для совпадения по префиксу; строка запроса игнорируется. Пустой список включения означает любую страницу, а совпадение с исключением всегда сильнее совпадения с включением.
  • Поведение. Задержка в секундах, глубина прокрутки от 0 до 100 %, намерение уйти и минимальный номер визита.
  • Аудитория. До 20 сегментов; посетитель должен входить хотя бы в один из них, а не во все. Сегменты вычисляются на сервере, поэтому браузер никогда не узнаёт определение сегмента: тому, кто не подходит, правило просто не отправляется.
  • Устройство. Десктоп, мобильный, планшет; если ничего не выбрано: любое устройство.

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

Частота ограничивает, как часто один посетитель это видит: максимум показов, пауза в часах и «остановить после конверсии». Новый поп-ап получает намеренно осторожные значения по умолчанию: 3 показа, пауза 24 часа и остановка после конверсии. Ноль в «показывать не больше» означает «без ограничения по числу», а не «никогда»: полностью остановить поп-ап можно только выключив его. Браузер хранит локальную отметку только чтобы не мигнуть поп-апом, который сервер всё равно отклонит: настоящая гарантия: состояние частоты на сервере.

Если на странице подходят несколько поп-апов, выигрывает тот, у кого меньше номер приоритета.

Два и более варианта превращают поп-ап в A/B-тест, максимум пять: посетители делятся по весам, устойчиво между визитами. Проверка перед активацией предупреждает, что эксперимент поп-апа использует цель конверсии по умолчанию и окно атрибуции в 30 дней.

Кнопки

В поп-апе может быть до пяти кнопок, и кнопка делает ровно одно из пяти действий: закрыть поп-ап, открыть чат, перейти по https://-ссылке, отправить форму или записать событие аналитики. Произвольного callback, JavaScript и свободного HTTP-адреса нет. У каждой кнопки должен быть уникальный технический ключ в нижнем регистре и подпись не длиннее 80 символов, а кнопка «отправить форму» отклоняется в поп-апе без формы. Некорректный список действий отбрасывается целиком, а не применяется частично, и на сервере, и в виджете.

Формы заявок

Форма собирает до 12 полей. Типы полей: короткий текст, email, телефон, список вариантов, флажок и скрытое поле. У каждого поля есть уникальный технический ключ в нижнем регистре, и ключи, похожие на чувствительные, отклоняются: всё, что содержит password, passwd, pwd, token, secret, card, cvv, cvc, government, passport, ssn, authorization или cookie, причём подчёркивания не спасают: pass_word тоже отклоняется. Не запрашивайте в поп-апе пароли и платёжные данные.

Значения ограничены: максимальная длина не больше 400 символов (у поля email от 64 до 254), не больше 50 уникальных вариантов не длиннее 120 символов каждый, телефон в виде + и от 7 до 15 цифр, у флажка только true или false. Скрытое поле всегда берёт значение из сохранённого на сервере описания, а не из браузера, даже если браузер прислал ту же константу. Значение поля, которого в форме нет, отклоняется целиком. Можно требовать явного согласия перед отправкой формы.

Поле может записываться в свойство профиля (property.<имя>). Email и телефон остаются обычными свойствами профиля. Они не создают и не подтверждают контакт в канале, поэтому два посетителя никогда не склеиваются просто из-за одинакового адреса, а сама отправка формы не создаёт согласия на маркетинговые письма.

Каждая отправка несёт ключ идемпотентности, поэтому двойной клик или повтор запишут одну заявку, а не две.

Что мешает активировать поп-ап

Активация проходит проверку на сервере и запрещается, если верно хотя бы одно:

  • виджет на сайте не подключён, выключен или у него нет ни одного разрешённого origin;
  • правило таргетинга по страницам использует origin, которого нет в разрешённых origin виджета;
  • выбранный сегмент больше не существует или не готов;
  • версия контента отсутствует, не опубликована или в архиве;
  • контент использует блоки, которые рендерер поп-апов на сайте показать не может;
  • некорректно настроены форма или кнопки;
  • веса вариантов A/B-теста нельзя распределить.

Проверка запускается при каждом сохранении поп-апа с включённым «Показывать посетителям». Заблокированная активация возвращается как 400 с полным отчётом, неподтверждённые предупреждения: как 409, пока не отмечена галочка подтверждения. Выключенный поп-ап можно сохранить, даже если что-то из перечисленного не исправлено.

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

Уведомления в браузере

Виджет также умеет спрашивать у посетителя разрешение на браузерные уведомления, и Web Push настраивается на этом же экране. Для него нужен шаг, который нельзя сделать из одного кабинета: файл сервис-воркера должен отдаваться с вашего собственного домена. Настройка, ограничения содержимого и то, чего браузерный пуш пока не умеет, описаны на странице «Пуш в браузере».

Ограничения первого релиза

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

Устранение неполадок

  1. Убедитесь, что фрагмент есть ровно один раз, в правильном порядке и с непустым ключом.
  2. Проверьте, что origin страницы точно совпадает с сохранённым разрешённым origin.
  3. Запустите автоматическую диагностику и различайте статические признаки и подтверждение в реальном браузере.
  4. Проверьте сообщения CSP в консоли браузера и повторите тест без блокировщиков контента.
  5. Если виджет открывается, но не даёт полезного ответа, настройте подходящие реакции.
  6. Если проблема остаётся, обратитесь в поддержку, приложив результат диагностики.