🔧 Установка виджета

Пошаговое руководство: как создать канал «Виджет» (чат для сайта) и установить его на свои страницы.

Цель

Добавить на сайт кнопку чата: посетитель пишет прямо со страницы — обращение попадает в «Поддержка» → «Чаты», и оператор отвечает из Fixorix.

Что понадобится

• Доступ к проекту Fixorix — достаточно любой роли участника проекта.
• Домен сайта, на который встанет виджет (например, example.ru).
• Сайт должен открываться по HTTPS — чат встраивается только на защищённые страницы.
• Возможность вставить тег <script> в HTML страниц (доступ к коду сайта или к настройкам CMS).

Шаг 1. Создайте канал

1. В левом меню в группе «Проект» откройте раздел «Каналы».

2. Нажмите «Создать» — откроется окно «Создание канала».

3. В поле «Платформа» выберите «Виджет».

4. Заполните поля:

   Поле	Обязательно	Что вводить
   Название	да	Имя канала, например «Чат поддержки».
   Описание	нет	Заметка для себя, например «виджет на лендинге».
   Укажите домен сайта	да	Домен сайта, например example.ru. Схему https:// можно не убирать — она отбросится сама.

5. Нажмите «Далее».

📷 Скриншот: первый шаг мастера — название, описание и домен (будет добавлен).

Домен — без порта

Указывайте только имя хоста: example.ru, localhost. Домен, сохранённый вместе с портом (localhost:3000), работать не будет — при проверке порт отбрасывается, и виджет получит отказ.

Домены общие для проекта

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

Шаг 2. Настройте внешний вид

Откроется экран «Внешний вид виджета». На широком экране рядом показывается живое превью — оно сразу отражает изменения.

Настройка	По умолчанию	Что задаёт
Основной цвет	тёмно-фиолетовый	Цвет кнопки-лаунчера и шапки чата.
Оттенок текста	фиолетовый	Дополнительный цвет оформления чата.
Позиция виджета	Справа	«Слева» или «Справа» — угол экрана, в котором появляется кнопка чата.
Показывать аватар оператора	включено	Показывать ли лицо оператора в переписке.
Задержка автооткрытия, сек	-1	Через сколько секунд чат откроется сам. -1 отключает автооткрытие, максимум — 60 секунд.
Приветственное сообщение	пусто	Первое сообщение, которое увидит посетитель. До 256 символов.

Кнопка «Назад» возвращает к первому шагу. Когда всё готово, нажмите «Создать».

Пока не работает

«Показывать аватар оператора» и «Приветственное сообщение» сохраняются и видны в превью, но на сайт не передаются: посетитель увидит аватар по умолчанию и стандартный текст «Здравствуйте! Чем можем помочь?». Цвета, позиция и задержка автооткрытия применяются как заданы.

Шаг 3. Установите сниппет на сайт

Откроется экран «Виджет готов».

1. В блоке «Вставьте это на сайт» скопируйте код кнопкой «Скопировать». Выглядит он так:

   <script src="https://widget.fixorix.ru/loader.js?widgetId=ВАШ-WIDGET-UUID" async></script>

   Вместо ВАШ-WIDGET-UUID в вашем сниппете уже подставлен идентификатор виджета — тот же, что показан в поле «ID виджета».

2. Вставьте код в HTML каждой страницы, где нужен чат, — лучше всего перед закрывающим тегом </body>.

3. Сохраните HMAC-секрет, если планируете опознавать авторизованных пользователей (см. ниже).

4. Нажмите «К списку каналов».

📷 Скриншот: экран «Виджет готов» со сниппетом и HMAC-секретом (будет добавлен).

Два варианта сниппета

В карточке виджета код установки предлагается в двух режимах — «Без авторизации» и «С авторизацией». Второй добавляет к сниппету идентификатор пользователя и подпись; рядом есть ссылка «Документация по подключению».

Тег должен быть настоящим

Виджет читает свой идентификатор из адреса самого тега <script>, поэтому код нужно вставлять прямо в разметку страницы. Если тег добавляется скриптом уже после загрузки страницы (через JS, обёртки вроде next/script и т. п.), виджет не запустится. Для таких случаев есть программный запуск:

<script src="https://widget.fixorix.ru/loader.js"></script>
<script>
  window.fixorixWidget.init({ widgetId: 'ВАШ-WIDGET-UUID' })
</script>

Секрет показывается один раз

HMAC-секрет вида widsk_… нужен для серверной подписи и опознания пользователей. Он отображается только на этом экране и больше не будет доступен. Сохраните его в надёжном месте сразу.

Если секрет утерян, выпустите новый в карточке виджета кнопкой «Сбросить секрет» — интерфейс предупредит: «Текущий HMAC-секрет перестанет работать сразу после сброса». На деле прежний секрет отзывается не мгновенно — у него есть короткий период дожития, — но рассчитывать на это не стоит: обновите секрет в серверной интеграции сразу.

Шаг 4. Проверьте виджет

1. Откройте сайт на указанном домене по HTTPS. В нижнем правом (или левом — как выбрали) углу появится круглая кнопка чата.
2. Нажмите её — откроется панель чата размером примерно 380×620 px; на узких экранах она разворачивается на всю ширину. Если задана задержка автооткрытия, панель откроется сама через указанное время.
3. Напишите тестовое сообщение из виджета. Enter отправляет, Shift+Enter переносит строку.
4. Откройте «Поддержка» → «Чаты» — обращение появится в списке слева.

Что делать дальше с обращением — Первое обращение.

Шаг 5. Как выключить и снова включить виджет

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

Так удобно временно снять чат с сайта (например, на время отпуска команды), не трогая код страниц.

Опознание авторизованных пользователей

Если посетитель уже вошёл в личный кабинет на вашем сайте, передайте виджету его идентификатор и подпись — тогда переписка будет общей на всех его устройствах.

1. На своём сервере посчитайте userHash = HMAC-SHA256(HMAC-секрет, userId) и отдайте результат странице в шестнадцатеричном виде, в нижнем регистре.
2. Передайте userId и userHash виджету — параметрами в адресе сниппета или через window.fixorixWidget.init({ widgetId, userId, userHash, email }).

Секрет остаётся на вашем сервере и в браузер не попадает. Если подпись не сойдётся, чат откроется анонимно. Подробнее — Виджет.

Ограничения

• Виджет предлагает только чат. Обратного звонка, email-формы и формы «представьтесь перед чатом» в нём нет: компонент такой формы существует, но посетителю никогда не показывается.
• Аватар оператора и приветственное сообщение из настроек до сайта не доезжают — см. предупреждение в шаге 2.
• Настроек рабочего времени и текста «вне рабочего времени» нет. На вкладке «Чат» карточки виджета указано: «Скоро здесь появятся настройки таймеров и графика работы».
• Размер файла, который посетитель прикладывает в виджете, — до 10 МБ. При превышении в чате появляется «⚠️ Не удалось загрузить файл». У оператора в дашборде лимит строже — 1 МБ.
• Виджет работает только по HTTPS.

Возможные проблемы

Симптом	Причина и решение
Кнопки чата нет вовсе	Скрипт не загрузился или в его адресе нет widgetId. В консоли браузера — [widget loader] widgetId is required. Проверьте, что тег <script> стоит в разметке страницы, а не добавляется скриптом.
Кнопка чата есть, но чат не открывается	Домен страницы не входит в список разрешённых для проекта либо виджет выключен кнопкой «Выключить виджет». В консоли — [widget loader] Error loading widget. Проверьте домен на вкладке «Основные» и состояние виджета в карточке канала.
Виджет не открывается на локальном стенде	Страница чата встраивается только по HTTPS. По http://localhost браузер заблокирует фрейм, даже если домен localhost разрешён. Проверяйте через HTTPS-адрес: локальный TLS или туннель.
Кнопка «Далее» не активна	Домен введён некорректно. Оставьте только имя хоста, без пути и без порта.
«Введите корректный домен»	Сообщение появляется в панели «Редактирование виджета» на вкладке «Основные». Исправьте значение поля «Привязанный домен».
Сообщения из виджета не приходят	Убедитесь, что виджет включён, и что в консоли браузера нет ошибок загрузки.
Цвет или позиция не изменились	Виджет запрашивает настройки при загрузке страницы. Сохраните изменения в панели «Редактирование виджета» и обновите страницу сайта.
Аватар и приветствие не такие, как в превью	Эти две настройки до сайта не доезжают — см. предупреждение в шаге 2.
Посетитель не может отправить файл	Файл больше 10 МБ: прокси виджета отвечает «file too large (max 10MB)», в чате видно «⚠️ Не удалось загрузить файл».

Что дальше

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