# API JavaScript widżetu czatu > Wszystkie polecenia API JavaScript widżetu czatu: init, identify, update, setTags, track, setContext, open, on i off, reset i destroy, z przykładami. Strona steruje widżetem czatu przez jedną funkcję `HrcWidget`: mówi, kim jest odwiedzający, otwiera i zamyka okno, nasłuchuje zdarzeń. Każde wywołanie wygląda tak: `HrcWidget('', ...argumenty)`. ## Ładowanie i kolejka Użyj [pełnego kodu do osadzenia](https://hrc.lt/pl/docs/widget/install). Wywołania sprzed pobrania skryptu ładującego czekają w kolejce `HrcWidget.q` i wykonują się po kolei, razem z funkcjami (callback). Wywołania po skrypcie ładującym, ale przed `init`, są przechowywane do 100; po przepełnieniu najpierw odrzucany jest `track`, nigdy `identify`, `reset` ani `on`. Zła wartość lub nieznane polecenie nigdy nie rzuca błędu na twojej stronie: zostaje pominięte z jednym ostrzeżeniem w konsoli. `debug: true` powie więcej. ## Typy TypeScript Typy ze wszystkimi poleceniami: [https://widget.hrc.lt/v1/hrc.d.ts](https://widget.hrc.lt/v1/hrc.d.ts). Pobierz plik do swojego kodu: ```ts // Pobierz do projektu: // https://widget.hrc.lt/v1/hrc.d.ts /// // edytor sprawdza typy HrcWidget('open', { view: 'new', type: 'question' }); ``` ## init Uruchamia widżet. Ponowne `init` z innym kluczem wyłącza stary widżet i uruchamia nowy. ```js HrcWidget('init', { // z twojego kodu do osadzenia widgetKey: 'wk_xxxxxxxxxxxxxxxxxxxx', // lub 'lt', 'en', 'ru', 'pl', ... locale: 'auto', // działa jak update profile: { attributes: { plan: 'pro' } }, context: { appVersion: '3.8.1', custom: { page_type: 'checkout' }, }, // 'hidden' dla własnego przycisku launcher: 'default', zIndex: 2147483000, // true: loguje odrzucone wartości debug: false, }); ``` | Opcja | Wartość | | ----------- | ------------------------------------------------------------- | | `widgetKey` | Klucz widżetu z karty „Instalacja”. Wymagany. | | `locale` | `'auto'` albo kod języka, np. `'lt'`. | | `identity` | To samo co `identify`. | | `profile` | To samo co `update`, stosowane, gdy odwiedzający ma sesję. | | `context` | To samo co `setContext`. | | `launcher` | `'default'` albo `'hidden'` (przycisk ukryty, `open` działa). | | `zIndex` | Warstwa widżetu, domyślnie 2147483000. | | `debug` | `true` wyjaśnia w konsoli pominięte wartości. | ## identify Rozpoznaje zalogowanego użytkownika: widzi on swoje rozmowy na każdym urządzeniu. `userHash` liczy twój serwer, zobacz [Weryfikacja tożsamości](https://hrc.lt/pl/docs/widget/identity-verification). Razem z nim możesz przekazać pola profilu. ```js HrcWidget('identify', { // ID użytkownika, zawsze tekst externalId: String(user.id), email: user.email, name: user.name, // zob. „Weryfikacja tożsamości” userHash: userHashFromYourServer, company: { id: 'acme-1', name: 'Acme', plan: 'Pro' }, attributes: { plan: 'pro', seats: 12, trial_ends_at: '2026-12-01' }, tags: ['vip'], }); ``` ## update Częściowo aktualizuje profil odwiedzającego: imię, telefon, awatar, firmę i do 50 własnych pól. Pola łączą się po jednym; `null` lub `''` usuwa pole. Wywołania w ciągu 500 ms idą razem. Zasady i limity: [Profil odwiedzającego](https://hrc.lt/pl/docs/widget/visitor-profile). ```js HrcWidget('update', { phone: '+370 600 00000', company: { name: 'Acme', website: 'https://acme.example', plan: 'Pro', }, // liczba, tak/nie, data lub tekst attributes: { orders: 14, newsletter: true, signed_up_at: new Date('2024-03-12'), app_version: '3.8.1', // null lub '' usuwa klucz coupon: null, }, }); ``` ## setTags Tablica dodaje tagi, obiekt dodaje i usuwa. Do 20 tagów na kontakt, litery, cyfry i myślnik. ```js // dodaje te tagi HrcWidget('setTags', ['vip', 'beta']); // dodaje i usuwa HrcWidget('setTags', { add: ['churn-risk'], remove: ['beta'] }); ``` ## track Zapisuje jedno działanie odwiedzającego. Zespół widzi 5 najnowszych na pasku bocznym, a wszystkie na stronie kontaktu. ```js HrcWidget('track', 'plan-upgraded', { from: 'free', to: 'pro' }); HrcWidget('track', 'checkout.failed', { reason: 'card_declined', amount: 49.9, }); ``` ## setContext Zastępuje wartości sesji wysyłane z każdą kolejną wiadomością. Nie są zapisywane w profilu. Do 20 własnych kluczy, wartość do 200 znaków. ```js // Tylko dla kolejnych wiadomości wizyty HrcWidget('setContext', { appVersion: '3.8.1', custom: { cart_id: 'c-1042', step: 'payment' }, }); ``` ## open, close, toggle i przycisk `open` otwiera okno: `view` to `'home'`, `'new'` lub `'list'`, `type` to `'bug'`, `'feature'` lub `'question'`. Z `view: 'new'` opcja `message` wpisuje tekst w pole nowej rozmowy (nie wysyła, do 2000 znaków). ```js // ekran startowy HrcWidget('open'); // rozmowy odwiedzającego HrcWidget('open', { view: 'list' }); // od razu formularz błędu HrcWidget('open', { view: 'new', type: 'bug' }); // tekst w polu, niewysłany HrcWidget('open', { view: 'new', message: 'Order #1042: ' }); HrcWidget('close'); HrcWidget('toggle'); // open() nadal działa HrcWidget('hideLauncher'); HrcWidget('showLauncher'); ``` ## on i off: zdarzenia ```js function onUnread(event) { document.title = event.count ? '(' + event.count + ') Shop' : 'Shop'; } // od razu z bieżącą liczbą HrcWidget('on', 'unread', onUnread); HrcWidget('on', 'ready', function (event) { console.log(event.isIdentified, event.locale); }); HrcWidget('on', 'conversation-started', function (event) { console.log(event.type); }); // usuwa tę funkcję HrcWidget('off', 'unread', onUnread); // usuwa wszystkie funkcje ready HrcWidget('off', 'ready'); ``` | Zdarzenie | Dane | Kiedy | | ---------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `ready` | `{ isIdentified, hasConversations, unreadCount, locale }` | Widżet wystartował. Dodane później `on('ready')` od razu dostaje ostatnią wartość. | | `open` | `{ view }` | Przy każdym otwarciu. | | `close` | `{}` | Przy każdym zamknięciu. | | `unread` | `{ count }` | Od razu z bieżącą wartością, potem przy każdej zmianie. | | `message` | `{ unreadCount }` | Przyszła odpowiedź zespołu, której odwiedzający jeszcze nie przeczytał. Bez tekstu, by inne skrypty na stronie nie czytały odpowiedzi. | | `conversation-started` | `{ conversationId, type }` | Odwiedzający rozpoczął rozmowę. | | `identified` | `{}` | `identify` się powiodło. | | `identify-failed` | `{ code }` | `identify` się nie powiodło, np. `IDENTITY_INVALID`. | Callback, który rzuca błąd, zapisuje jedno ostrzeżenie i nie zatrzymuje ani widżetu, ani innych callbacków. ## setLocale, reset i destroy ```js // zmienia język od razu, albo 'auto' HrcWidget('setLocale', 'pl'); // wylogowanie: zapomina odwiedzającego HrcWidget('reset'); // usuwa widżet; potem znów init HrcWidget('destroy'); ``` `reset` zapomina sesję, rozpoznanie oraz wszystkie jeszcze niewysłane zmiany profilu, tagi, działania i wartości sesji. Wywołuj go, gdy użytkownik się wylogowuje. ## Aplikacje jednostronicowe Zmianę strony (`pushState`, `popstate`) skrypt ładujący wykrywa sam, więc w wiadomościach widać prawdziwą stronę. Przykład dla React: [Kod do osadzenia, React i CSP](https://hrc.lt/pl/docs/widget/install).