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

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

Цель

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

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

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

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

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

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

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

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

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

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

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

Домен — без порта и точно как в адресной строке

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

Домен сравнивается точно: www.example.ru и example.ru — разные домены. Если сайт открывается по обоим адресам, добавьте оба (см. «Домен виджета»).

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

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

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

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

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

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

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

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

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

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

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

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

   Вместо ВАШ-WIDGET-UUID в вашем сниппете уже подставлен идентификатор виджета — тот же, что показан ниже в блоке «Тех. информация» (строка «Widget ID») и в панели «Детали виджета» (поле «ID виджета»).

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

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

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

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

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

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

Подключайте загрузчик обычным тегом

Загрузчик определяет свой адрес и идентификатор виджета по собственному тегу <script>. Поэтому подключайте loader.js обычным тегом <script src=…> — прямо в разметке страницы или вставленным через document.createElement('script'), — а не через import, eval или сборщик: иначе виджет не запустится.

Если виджет нужно запускать из кода, подключите loader.js без параметров и передайте настройки через очередь — так же устроен сниппет «С авторизацией»:

<script src="https://widget.fixorix.ru/loader.js" async></script>
<script>
  var fx = (window.fixorixWidget = window.fixorixWidget || {});
  var config = { widgetId: "ВАШ-WIDGET-UUID" };
  fx.init ? fx.init(config) : (fx.q = fx.q || []).push([config]);
</script>

Когда загрузчик уже на странице, можно вызывать и напрямую: window.fixorixWidget.init({ widgetId: "ВАШ-WIDGET-UUID" }).

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

HMAC-секрет (строка из 64 шестнадцатеричных символов) нужен для серверной подписи и опознания пользователей. Он отображается только на этом экране и больше не будет доступен. Сохраните его в надёжном месте сразу.

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

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

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

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

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

В строке виджета в разделе «Каналы» (колонка «Управление») есть кнопка ▶/■ с подсказкой «Выключить виджет» / «Включить виджет». Выключенный виджет на сайте не открывается: кнопка чата видна, но по нажатию панель не появляется. Сниппет при этом убирать не нужно.

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

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

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

1. На своём сервере посчитайте userHash = HMAC-SHA256(HMAC-секрет, userId) и отдайте результат странице.
2. Передайте userId и userHash (и при желании email) виджету — в сниппете режима «С авторизацией» или параметрами в адресе сниппета.

Правила подписи:

• Ключ — HMAC-секрет в том виде, в каком он выдан (строка из 64 символов), как текст: ничего к нему не добавляйте и не декодируйте из hex.
• Подписывается ровно тот userId, который передаётся виджету.
• Результат — шестнадцатеричная строка в нижнем регистре.
• Если передаёте email, он должен быть корректным адресом — иначе опознание не пройдёт и чат откроется анонимно.
• Во время смены секрета подпись принимается и по новому, и по прежнему секрету, пока тот не отозван.

Node.js

const crypto = require('crypto')
const userHash = crypto.createHmac('sha256', SECRET).update(String(userId)).digest('hex')

Python

import hashlib, hmac
user_hash = hmac.new(SECRET.encode(), str(user_id).encode(), hashlib.sha256).hexdigest()

Сниппет режима «С авторизацией» в интерфейсе выглядит так — подставьте свои значения вместо USER_ID, USER_HASH и адреса почты:

<script src="https://widget.fixorix.ru/loader.js" async></script>
<script>
  var fx = (window.fixorixWidget = window.fixorixWidget || {});
  var config = {
    widgetId: "ВАШ-WIDGET-UUID",
    userId: "USER_ID",
    userHash: "USER_HASH",
    email: "user@example.com"
  };
  fx.init ? fx.init(config) : (fx.q = fx.q || []).push([config]);
</script>

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

Ограничения

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

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

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

Что дальше

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