# Код для вставлення, React і CSP

> Код для вставлення чат-віджета, черга команд, React та інші SPA, Next.js, Content Security Policy, дозволені адреси й часті проблеми.

Усе, що потрібно розробнику, щоб додати чат-віджет: код, односторінкові застосунки, CSP і дозволені адреси. Швидкий шлях без програмування: [Встановлення чат-віджета на сайт](https://hrc.lt/uk/docs/getting-started/install-widget).

## Короткий код

Ключ віджета є в розділі «Налаштування», «Чат-віджети», «Встановлення». Код завантажується асинхронно й не гальмує сайт.

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

Необов'язковий атрибут `data-locale` задає мову (за замовчуванням `auto`).

## Повний код із чергою команд

Цей код одразу створює функцію `HrcWidget`, тож її можна викликати ще до завантаження віджета. Виклики чекають у черзі `HrcWidget.q` і виконуються по черзі, коли завантажувач завантажиться.

```html
<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 немає: скопіюйте цей хук. Він завантажує віджет один раз і тримає розпізнавання користувача в узгодженні з вашим входом.

```tsx
// 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, дозвольте адресу віджета:

```text
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](https://hrc.lt/uk/docs/widget/javascript-api).