# Valdiklio įdėjimas: kodas, React ir CSP

> Pokalbių valdiklio įdėjimo kodas, komandų eilė, React ir kitos SPA, Next.js, Content Security Policy, leidžiami domenai ir dažnos klaidos.

Šiame puslapyje rasite viską, ko reikia programuotojui įdedant pokalbių valdiklį: kodą, SPA, CSP ir leidžiamus domenus. Greitas kelias be programavimo yra [Pokalbių valdiklio įdėjimas į svetainę](https://hrc.lt/dokumentacija/pradzia/valdiklio-idejimas).

## Trumpasis kodas

Valdiklio raktą rasite skiltyje Nustatymai, Pokalbių valdikliai, Įdėjimas. Kodas įkeliamas asinchroniškai ir svetainės nestabdo.

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

Nebūtinas atributas `data-locale` nurodo kalbą (pagal nutylėjimą `auto`).

## Pilnas kodas su komandų eile

Šis kodas sukuria `HrcWidget` funkciją iš karto, todėl jos kvietimus galite rašyti dar prieš įkeliant valdiklį. Kvietimai laukia eilėje `HrcWidget.q` ir įvykdomi iš eilės, kai įkėliklis atsisiunčia.

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

Jei įkėliklis įdėtas du kartus, veikia pirmasis. Jei puslapyje jau yra jūsų `init`, trumpojo kodo `data-widget-key` ignoruojamas.

## React ir kitos SPA

npm paketo nėra: nukopijuokite šį hook'ą. Jis įkelia valdiklį vieną kartą ir derina naudotojo atpažinimą su jūsų prisijungimu.

```tsx
// useSupportWidget.ts: įkelia valdiklį vieną kartą, seka prisijungimą
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]);
}

// Atidarymas savo mygtuku:
// hrc('open', { view: 'new', type: 'bug' })
```

- Puslapio keitimą (`pushState`, `popstate`) įkėliklis pastebi pats, nieko kviesti nereikia.
- Next.js ir kitur, kur puslapis kuriamas serveryje, hook'ą naudokite tik kliento komponente.
- `reset` be naudotojo pirmo atvaizdavimo metu nieko nesugadina: jis keičia tik atpažintą sesiją.

## Content Security Policy

Jei svetainė siunčia CSP antraštę, leiskite valdiklio adresą:

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

`data:` tarp `img-src` reikia ekrano nuotraukai vienu paspaudimu. Be jo nuotrauka daroma naršyklės langu. Paveikslėliai ir šriftai iš kitų domenų nuotraukoje nupiešiami tik tada, kai `connect-src` tuos domenus leidžia.

## Leidžiami domenai

Valdiklis veikia tik domenuose, nurodytuose skiltyje Bendra. Pridėkite kiekvieną kaip `https://shop.example.lt`. `https://*.example.lt` tinka visiems jūsų domeno subdomenams. Bendro naudojimo domenas, pavyzdžiui `*.vercel.app` ar `*.github.io`, žvaigždute negalimas: pridėkite tikslų adresą. Kūrimui įjunkite „Leisti localhost“.

## Jei valdiklis nepasirodo

- **Domenas neleidžiamas.** Patikrinkite, ar puslapio adresas yra leidžiamų domenų sąraše.
- **CSP.** Naršyklės konsolėje ieškokite pranešimo apie `widget.hrc.lt`.
- **Pakeistas raktas.** Pakeitus valdiklio raktą, senas nebeveikia: įdėkite naują kodą.
- **Daugiau informacijos.** `init` su `debug: true` konsolėje parodo, kodėl reikšmė ar komanda praleista. Visi įspėjimai prasideda `[support widget]`.

Visos komandos aprašytos puslapyje [JS API](https://hrc.lt/dokumentacija/valdiklis/js-api).