Kod do osadzenia, React i CSP

Wszystko, czego programista potrzebuje, by dodać widżet czatu: kod, aplikacje jednostronicowe, CSP i dozwolone adresy. Szybka droga bez programowania: Instalacja widżetu czatu na stronie.

Krótki kod

Klucz widżetu znajdziesz w „Ustawieniach”, „Widżety czatu”, „Instalacja”. Kod ładuje się asynchronicznie i nie blokuje strony.

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

Opcjonalny atrybut data-locale ustawia język (domyślnie auto).

Pełny kod z kolejką poleceń

Ten kod od razu tworzy funkcję HrcWidget, więc możesz ją wywoływać jeszcze przed załadowaniem widżetu. Wywołania czekają w kolejce HrcWidget.q i wykonują się po kolei, gdy skrypt ładujący się pobierze.

<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>

Jeśli skrypt ładujący jest wstawiony dwa razy, działa pierwszy. Jeśli strona ma już własne init, data-widget-key z krótkiego kodu jest pomijany.

React i inne SPA

Pakietu npm nie ma: skopiuj ten hook. Ładuje widżet raz i utrzymuje rozpoznawanie użytkownika w zgodzie z twoim logowaniem.

// useSupportWidget.ts: ładuje widżet raz i śledzi logowanie
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]);
}

// Otwieranie własnym przyciskiem:
// hrc('open', { view: 'new', type: 'bug' })

• Zmianę strony (pushState, popstate) skrypt ładujący wykrywa sam, nic nie trzeba wywoływać.
• W Next.js i przy renderowaniu po stronie serwera używaj hooka tylko w komponencie klienckim.
• reset bez użytkownika przy pierwszym renderowaniu niczego nie psuje: zastępuje tylko rozpoznaną sesję.

Content Security Policy

Jeśli strona wysyła nagłówek CSP, zezwól na adres widżetu:

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

data: w img-src jest potrzebne do zrzutu ekranu jednym kliknięciem. Bez tego zrzut robi się przez okno przeglądarki. Obrazy i czcionki z innych domen pojawiają się na zrzucie tylko wtedy, gdy connect-src na nie pozwala.

Dozwolone adresy

Widżet działa tylko pod adresami z karty „Ogólne”. Dodaj każdy jako https://shop.example.com. https://*.example.com obejmuje wszystkie subdomeny twojej domeny. Wspólnego hostingu, np. *.vercel.app czy *.github.io, nie można dodać z gwiazdką: dodaj dokładny adres. Do pracy nad stroną włącz „Zezwól na localhost”.

Jeśli widżet się nie pojawia

• Adres niedozwolony. Sprawdź, czy adres strony jest na liście dozwolonych.
• CSP. Poszukaj w konsoli przeglądarki komunikatu o widget.hrc.lt.
• Zmieniony klucz. Po zmianie klucza widżetu stary przestaje działać: wstaw nowy kod.
• Więcej szczegółów. init z debug: true wyjaśnia w konsoli, dlaczego wartość lub polecenie zostały pominięte. Każde ostrzeżenie zaczyna się od [support widget].

Wszystkie polecenia opisuje strona API JavaScript.