Очередь команд, порядок загрузки и правила, которые избавят от типичных ошибок.

Как устроен JS API

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

Что	Когда	Для чего
`window.SvyazioConfig`	до загрузки	Внешний вид, тексты, поведение, отдел, обработчики событий.
`window.SvyazioIntegration`	до загрузки	Данные о посетителе, которые сайт уже знает: имя, email, телефон, тариф.
`Svyazio('метод', …)`	в любой момент	Открыть или скрыть чат, сменить цвета и язык, передать данные.

Что происходит при загрузке

Скрипт читает SvyazioConfig. Если в нём нет orgId, виджет не запускается.
Проверяет устройство: при disabledOnMobile или mobileOnly на неподходящем устройстве виджет не запускается.
Загружает настройки из панели. Если виджет там выключен, дальше ничего не происходит. Параметры страницы накладываются поверх настроек панели.
Отмечает визит (страница, UTM-метки) и рисует кнопку.
Применяет startHidden, customWidgetButton и автооткрытие из панели.
Передаёт SvyazioIntegration, открывает чат, если в адресе есть #svyazioChatExpanded, и заменяет надписи из locale-объекта.
Сообщает onAnalyticEvent('Widget loaded') и выполняет накопленные вызовы Svyazio(…).

Что важно знать

Параметры страницы главнее панели. Всё, что задано в SvyazioConfig, перекрывает настройки из панели, но только на этой странице.
Виджет изолирован от стилей сайта. Он работает в Shadow DOM: CSS сайта его не ломает, а его стили не влияют на сайт. Поэтому менять вид через CSS сайта не получится — только параметрами и методами.
Повторная вставка кода безопасна. Если код попал на страницу дважды (шаблон и тег-менеджер), второй экземпляр не создаётся.
Ошибки виджета остаются внутри. Если виджет выключен или не смог загрузиться, вызовы Svyazio(…) просто ничего не делают и не ломают скрипты сайта.

Когда очередь команд теряется

Если в конфигурации нет orgId или виджет не смог запуститься, функция window.Svyazio всё равно объявляется, но экземпляра window.SvyazioWidget нет. Накопленные вызовы в этом случае молча отбрасываются — в консоли не будет ни одной ошибки. Первое, что стоит проверить при «метод не сработал»: есть ли window.SvyazioWidget (см. диагностику).

Без iframe, с открытым Shadow DOM

В отличие от Chatra, виджет не создаёт <iframe>. Он живёт в элементе div#svyazio-widget-container с открытым Shadow DOM, поэтому стили сайта на него не влияют, а его стили — на сайт. Открытый shadow-root означает, что при большом желании внутрь можно добавить свой <style> — но это не часть контракта: разметка внутри меняется с обновлениями без предупреждения. Для оформления используйте параметры внешнего вида и setColors.

Вес и загрузка

Скрипт svyazio.js — один файл около 165 КБ, грузится асинхронно и не блокирует отрисовку страницы. Внешних шрифтов и CDN он не подключает. При выключенном JavaScript виджет не отрисовывается вовсе — запасного <noscript>-варианта нет, поэтому на страницах, где важен контакт без JS, оставьте почту или телефон в разметке.

Блокировщики рекламы

Некоторые списки блокировщиков режут сторонние скрипты чатов. Если у части посетителей кнопка не появляется, а у вас — есть, проверьте сайт с включённым блокировщиком: в консоли будет ошибка загрузки svyazio.js, а window.SvyazioWidget — пустым.