Код для вставки, React и CSP

Всё, что нужно разработчику, чтобы установить чат-виджет: код, одностраничные приложения, CSP и разрешённые адреса. Быстрый путь без программирования: Установка чат-виджета на сайт.

Короткий код

Ключ виджета находится в разделе «Настройки», «Чат-виджеты», «Установка». Код загружается асинхронно и не тормозит сайт.

<script
  src="https://widget.hrc.lt/v1/loader.js"
  data-widget-key="wk_xxxxxxxxxxxxxxxxxxxx"
  async
></script>

Необязательный атрибут data-locale задаёт язык (по умолчанию auto).

Полный код с очередью команд

Этот код сразу создаёт функцию HrcWidget, поэтому её можно вызывать ещё до загрузки виджета. Вызовы ждут в очереди HrcWidget.q и выполняются по порядку, когда загрузчик загрузится.

<script>
  (function (w, d) {
    w.HrcWidget = w.HrcWidget || function () {
      (w.HrcWidget.q = w.HrcWidget.q || []).push(arguments);
    };
    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://widget.hrc.lt/v1/loader.js';
    d.head.appendChild(s);
  })(window, document);
  HrcWidget('init', {
    widgetKey: 'wk_xxxxxxxxxxxxxxxxxxxx',
    locale: 'auto',
  });
</script>

Если загрузчик вставлен дважды, работает первый. Если на странице уже есть ваш init, data-widget-key короткого кода игнорируется.

React и другие SPA

Пакета npm нет: скопируйте этот хук. Он загружает виджет один раз и держит распознавание пользователя в согласии с вашим входом.

// useSupportWidget.ts: загружает виджет один раз, следит за входом
import { useEffect } from 'react';

type Identity = {
  externalId?: string;
  email?: string;
  name?: string;
  userHash: string;
};
type Queue = ((...args: unknown[]) => void) & { q?: unknown[][] };
declare global {
  interface Window { HrcWidget?: Queue }
}

function hrc(...args: unknown[]) {
  if (!window.HrcWidget) {
    const queue: unknown[][] = [];
    const stub = (...a: unknown[]) => { queue.push(a); };
    window.HrcWidget = Object.assign(stub, { q: queue });
    const s = document.createElement('script');
    s.async = true;
    s.src = 'https://widget.hrc.lt/v1/loader.js';
    document.head.appendChild(s);
  }
  window.HrcWidget(...args);
}

export function useSupportWidget(options: {
  widgetKey: string;
  locale?: string;
  identity?: Identity | null;
}) {
  const { widgetKey, locale = 'auto', identity } = options;
  useEffect(() => {
    hrc('init', { widgetKey, locale });
  }, [widgetKey, locale]);
  useEffect(() => {
    if (identity) hrc('identify', identity);
    else hrc('reset');
  }, [identity?.externalId, identity?.email, identity?.userHash]);
}

// Открытие своей кнопкой:
// hrc('open', { view: 'new', type: 'bug' })

• Смену страницы (pushState, popstate) загрузчик замечает сам, ничего вызывать не нужно.
• В Next.js и при серверной отрисовке используйте хук только в клиентском компоненте.
• reset без пользователя при первой отрисовке ничего не ломает: он меняет только распознанную сессию.

Content Security Policy

Если сайт отправляет заголовок CSP, разрешите адрес виджета:

script-src https://widget.hrc.lt;
frame-src https://widget.hrc.lt;
img-src data:;

data: в img-src нужен для снимка экрана в один клик. Без него снимок делается через окно браузера. Изображения и шрифты с других доменов рисуются на снимке, только если connect-src их разрешает.

Разрешённые адреса

Виджет работает только на адресах, указанных на вкладке «Общие». Добавьте каждый как https://shop.example.com. https://*.example.com подходит для всех поддоменов вашего домена. Общий хостинг, например *.vercel.app или *.github.io, нельзя указать со звёздочкой: добавьте точный адрес. Для разработки включите «Разрешить localhost».

Если виджет не появляется

• Адрес не разрешён. Проверьте, есть ли адрес страницы среди разрешённых.
• CSP. Найдите в консоли браузера сообщение о widget.hrc.lt.
• Ключ изменён. После смены ключа виджета старый перестаёт работать: вставьте новый код.
• Подробности. init с debug: true объясняет в консоли, почему значение или команда пропущены. Все предупреждения начинаются с [support widget].

Все команды описаны на странице JavaScript API.