[Intum Pomoc](https://intum.pl/pomoc.md) / [Toolkit](https://intum.pl/pomoc/toolkit.md)

# [Widgety na stronę](https://intum.pl/pomoc/toolkit/toolkit-widgety.md)

Widget to kod, który wklejasz raz na swoją stronę, a co pokazuje i jak wygląda, ustawiasz potem
w panelu - bez zmiany kodu na stronie. Widgety konfigurują osoby zarządzające kontem.

> [!PATH]
> [Toolkit → Widgety](app:/toolkit/widgets) → **+**
> [Toolkit → Widgety](app:/toolkit/widgets) → *widget* → **Edycja**

> [!NOTE]
> Widgety są częścią Toolkitu, który jest zawsze włączony - nie trzeba go włączać na liście
> modułów konta.

## Rodzaj widgetu {#rodzaj}

Rodzaj wybierasz przy dodawaniu widgetu i potem się go nie zmienia - inny rodzaj to nowy widget.
Na razie jest jeden rodzaj:

- **Support Widget (pomoc, zgłoszenia, czat)** - jeden przycisk **Pomoc** w rogu Twojej strony,
  który otwiera panel z zakładkami: **Pomoc** (artykuły bazy wiedzy z wyszukiwarką),
  **Zgłoszenia** (formularz zgłoszenia i lista zgłoszeń klienta) i **Czat** (rozmowa
  z operatorem). Zamiast wklejać na stronę osobno widget bazy wiedzy, widget zgłoszeń i czat,
  wklejasz jeden kod.

Dotychczasowe widgety (widget zgłoszeń desku, widget bazy wiedzy i widget czatu) działają dalej
bez zmian - Support Widget to dodatkowa możliwość, nie zastępuje ich.

## Sekcje {#sekcje}

- **Baza wiedzy (sekcja Pomoc)** - wybierz bazę wiedzy, z której klient czyta artykuły. Pusty
  wybór wyłącza zakładkę.
- **Artykuły pomocy** - **Otwieraj w widgecie** (domyślnie) pokazuje kliknięty artykuł w panelu,
  z przyciskiem **Wróć** do listy i ikoną otwarcia w nowym oknie. Linki w treści artykułu
  otwierają się w nowej karcie. **Otwieraj w nowej karcie** przenosi klienta na stronę bazy wiedzy.
- **Nowości** - na starcie zakładki **Pomoc** klient widzi listy **Popularne**, **Najnowsze**
  i **Kategorie**. Gdy baza ma wpisy [changelogu](app:/kb/help/na_stronie/changelog), a changelog
  jest włączony w module Bazy wiedzy, w miejscu **Najnowszych** pojawiają się **Nowości** - kilka
  ostatnich wpisów changelogu z datą i początkiem treści oraz link do pełnej strony nowości.
  Wpis powiązany z artykułem bazy otwiera ten artykuł (tak jak ustawiono w **Artykuły pomocy**),
  pozostałe - adres z treści wpisu albo stronę changelogu. Kropka przy **Nowościach** oznacza wpis,
  którego klient jeszcze nie oglądał (z ostatnich 30 dni) - gaśnie po otwarciu tej listy.
- **Desk (sekcja Zgłoszenia)** - desk, do którego trafiają zgłoszenia z Support Widgetu - z jego
  kategoriami, załącznikami, odpowiedzią AI i powiadomieniami mailem, tak jak w [zwykłym
  widgecie](app:/helpdesk/help/portal_i_widget/widget_na_stronie#co-widzi-klient). Pusty wybór wyłącza zakładkę.
- **Widget czatu (sekcja Czat)** - widget WebChatu, z którym klient rozmawia w zakładce. Godziny
  otwarcia, operatorzy, wymagane dane, załączniki i dźwięki są te same, co ustawione w [tym
  widgecie czatu](app:/webchat/help/widgety/widget#pola), a rozmowy trafiają do zwykłego panelu
  operatora. Pusty wybór wyłącza zakładkę.
- **Nazwa zakładki** - własny napis zamiast domyślnego *Pomoc* / *Zgłoszenia* / *Czat*.
- **Zakładka startowa** - która zakładka jest otwarta po kliknięciu przycisku. Bez wyboru otwiera
  się pierwsza włączona.

Sekcja pojawia się w formatce tylko wtedy, gdy jej moduł jest włączony na koncie: **Pomoc** - baza
wiedzy, **Zgłoszenia** - Helpdesk, **Czat** - WebChat. Gdy później wyłączysz moduł, jego zakładka znika z widgetu na
stronie, a pozostałe działają dalej.

Musi być włączona co najmniej jedna sekcja. Gdy włączona jest tylko jedna, panel nie pokazuje
zakładek - od razu jej treść.

> [!WARNING]
> Na jednej stronie może działać tylko jeden czat. Gdy Support Widget ma zakładkę **Czat**, nie
> wklejaj na tę samą stronę osobnego kodu widgetu czatu - użyj **Ukryj na stronach** w jednym
> z nich, jeśli oba są potrzebne w różnych miejscach serwisu.

## Wygląd {#wyglad}

**Tytuł panelu**, **Napis na przycisku**, **Język** (napisy panelu i sekcji), **Położenie** (prawa
albo lewa strona ekranu) i **Kolor** przycisku i nagłówka (w formacie `#rrggbb`, np. `#2563eb`).
Na telefonie panel otwiera się na cały ekran.

**Wygląd przycisku** - jak klient otwiera panel:

- **Przycisk z napisem** - znak zapytania i napis w dolnym rogu strony (domyślnie),
- **Okrągła ikona** - sam znak zapytania w dolnym rogu, napis pokazuje się w dymku,
- **Zakładka na boku ekranu** - pionowa zakładka przyklejona do brzegu w połowie wysokości,
- **Schowany przy krawędzi** - przy dolnym rogu wystaje tylko znak zapytania, a przycisk z napisem
  wysuwa się po najechaniu myszą. Najmniej zasłania stronę. Gdy na czacie czeka nieprzeczytana
  wiadomość, przycisk wysuwa się sam.

Warianty porównasz bez zapisywania na stronie **Testuj** - nad stroną testową jest przełącznik
wyglądu przycisku. Na wybranych stronach serwisu możesz też pokazać inny wariant: dopisz w kodzie
`launcher_style: "peek"` (albo `button`, `icon`, `tab`).

### Sposób otwierania panelu {#panel}

- **Okno w rogu** - panel otwiera się nad przyciskiem, w rogu strony (domyślnie).
- **Panel z boku strony** - panel wysuwa się z boku (prawego albo lewego, wg **Położenia**) na całą
  wysokość ekranu. Ma więcej miejsca na artykuły i czat, ale przykrywa brzeg strony.
- **Panel z boku, strona się zwęża** - jak wyżej, ale Twoja strona przesuwa się i robi miejsce na panel,
  więc niczego nie zasłania. Klient czyta pomoc obok treści strony.

Przy zwężaniu strony:

- elementy przyklejone do ekranu na Twojej stronie (np. nagłówek, który zostaje u góry przy przewijaniu,
  pasek ciasteczek, inny czat) nie przesuwają się razem ze stroną i mogą częściowo schować się pod panel,
- na węższym oknie (poniżej ok. 1024 px) strona się nie zwęża - panel ją przykrywa, a na telefonie
  otwiera się na cały ekran, jak w każdym sposobie,
- panel nie otwiera się sam po przejściu na kolejną podstronę, bo strona przeskoczyłaby zaraz po
  załadowaniu - klient otwiera go przyciskiem.

Sposoby porównasz na stronie **Testuj** (przełącznik nad stroną testową). Na wybranych stronach serwisu
możesz pokazać inny sposób, dopisując w kodzie `panel_mode: "drawer"` (albo `popup`, `push`).

## Widoczność na stronach {#widocznosc}

**Pokaż tylko na stronach** i **Ukryj na stronach** - po jednym adresie w linii, `*` zastępuje
dowolny fragment (np. `*/panel/*`). Puste **Pokaż tylko na stronach** oznacza wszystkie strony.

## Co widget pamięta między stronami {#pamiec}

Gdy klient przechodzi na inną podstronę, Support Widget wraca do tego, co miał otwarte:

- ostatnio wybraną zakładkę,
- otwarty artykuł albo kategorię pomocy,
- obejrzane **Nowości** - kropka nie wraca na kolejnych stronach, dopóki nie pojawi się nowszy wpis,
- rozwinięty panel - na komputerze panel otwiera się sam na kolejnej stronie; na telefonie startuje
  zamknięty, bo zasłaniałby całą stronę (tak samo przy [panelu zwężającym stronę](#panel)). Zamknięcie panelu krzyżykiem też jest zapamiętywane,
- rozmowę na czacie - przez 24 godziny od ostatniej wiadomości widget łączy się z czatem na każdej
  podstronie, a nowa odpowiedź operatora pokazuje licznik na przycisku **Pomoc** i na zakładce **Czat**.

Widget zapisuje to w ciasteczku na Twojej stronie dopiero wtedy, gdy klient pierwszy raz otworzy
panel - u odwiedzających, którzy go nie klikają, nie zapisuje nic i nie wczytuje nic poza samym
przyciskiem. Ciasteczko wygasa po 30 dniach bez używania widgetu i nie zawiera danych osobowych.
Wyłączony Support Widget (bez zaznaczonego **Aktywny**) nie pokazuje się nigdzie, mimo wklejonego kodu.

## Rozpoznawanie klienta {#rozpoznawanie-klienta}

- **Anonimowo (klient podaje e-mail)** - klient zakłada zgłoszenie, wpisując swój e-mail. Do
  zgłoszenia wraca linkiem albo kodem z maila (jak przy [zwykłym
  widgecie](app:/helpdesk/help/portal_i_widget/widget_na_stronie#co-widzi-klient)), ale nie widzi w Support Widgecie listy swoich
  zgłoszeń. Twoja strona może podać w kodzie `email` i `name` - wtedy formularz jest od razu
  wypełniony, ale same te dane nie dają dostępu do żadnych zgłoszeń.
- **Podpis z Twojej strony (HMAC)** - dla stron z logowaniem. Serwer Twojej strony podpisuje
  kluczem tajnym identyfikator i e-mail zalogowanego klienta, a Support Widget po sprawdzeniu podpisu
  pokazuje mu listę jego zgłoszeń. Bez poprawnego podpisu (np. na stronie dla niezalogowanych)
  Support Widget działa jak w trybie anonimowym.

Jeśli desk w ustawieniach zabezpieczeń wymaga podpisu, przyjmuje zgłoszenia z Support Widgetu tylko
od klientów rozpoznanych podpisem. Anonimowy odwiedzający dostanie przy wysyłce błąd autoryzacji -
do takiego desku ustaw w widgecie tryb **Podpis z Twojej strony**.

**Czat** w trybie anonimowym zaczyna rozmowę z nieznanym klientem (e-mail z kodu strony tylko
wypełnia formularz czatu). W trybie podpisu Support Widget sam podpisuje dla czatu tę samą tożsamość -
rozmowa trafia do klienta z CRM o zewnętrznym identyfikatorze równym `user_id`, także gdy widget
czatu ma włączony [podpis zabezpieczający](app:/webchat/help/widgety/widget#tozsamosc). Nie
potrzebujesz do tego klucza tajnego widgetu czatu - wystarczy podpis Support Widgetu.

### Jak policzyć podpis {#podpis}

Do kodu Support Widgetu dopisujesz pola zalogowanego klienta:

```html
<div data-intum-support-widget="xxxxxxxxxxxx" data-account-id="123"
  data-user-id="USR-123" data-email="jan@example.com" data-name="Jan Kowalski"
  data-identity-timestamp="1700000000" data-identity-signature="..."></div>
```

`data-identity-signature` to HMAC-SHA256 kluczem tajnym widgetu z tekstu
`["USR-123","jan@example.com","1700000000"]` (tablica JSON: `user_id`, e-mail małymi literami,
`data-identity-timestamp` - czas unix w sekundach przy wyświetleniu strony), zapisany szesnastkowo.
Podpis jest ważny 12 godzin. Gotowe przykłady w Ruby, Node.js i PHP są w kodzie do wklejenia na
karcie widgetu.

Klucz tajny jest na karcie widgetu (**Pokaż**). Gdy wycieknie, zaznacz w edycji **Wygeneruj
nowy klucz tajny** - stary przestaje działać od razu, więc zaktualizuj go też na serwerze strony.

> [!WARNING]
> Podpis licz zawsze na serwerze swojej strony - nigdy w kodzie widocznym dla przeglądarki.
> Klucz tajny w kodzie strony pozwala każdemu podszyć się pod dowolnego klienta.

## Kod na stronę i test {#kod-na-strone}

Kod do wklejenia jest na karcie widgetu - wklej go przed `</body>`. To jeden znacznik `<div>`
z ustawieniami strony i skrypt, bez dodatkowego skryptu z konfiguracją, więc działa także na stronach
z zaostrzonymi zasadami bezpieczeństwa (CSP). Zmiany ustawień (sekcje, wygląd, widoczność) docierają
na stronę same, w ciągu kilku minut, bez podmieniania kodu.

Linki do ekranów systemu w artykułach pomocy (np. *Ustawienia → Konto*) prowadzą na adres strony,
na której jest widget, i otwierają się w tej samej karcie - klient trafia do swojego konta. Gdy
widget wisi na innej domenie niż panel Twojej aplikacji (np. widget na `www.example.com`, panel na
`app.example.com`), dopisz w znaczniku `<div>` z kodu atrybut z adresem panelu, np.
`data-app-link-host="https://app.example.com"` (przykład jest w komentarzu kodu).

**Testuj** na karcie widgetu otwiera stronę testową z działającym Support Widgetem na przykładowej
stronie klienta, w kolorze widgetu - od razu widać, co widget zasłania, a przy panelu zwężającym
stronę - jak strona się przesuwa. U góry są przełączniki wyglądu przycisku i sposobu otwierania
panelu do porównania bez zapisywania. W trybie
podpisu strona testowa podpisuje testową tożsamość (`TEST-<Twoje id>`, adres w domenie
`example.com`), więc zgłoszenia z testu nie trafiają do prawdziwego klienta. Strona testowa pokazuje
zmiany od razu po zapisaniu ustawień, bez czekania kilku minut jak na Twojej stronie.