Valdiklio įdėjimas: kodas, React ir CSP

Š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ę.

Trumpasis kodas

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

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

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

// 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ą:

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.