@nexlylab/widget

Agent AI na dowolnej stronie w jednej linijce HTML. Bez builda, bez frameworka, bez konfiguracji.

Instalacja

Wklej przed </body>:

<script src="https://e-commerce-studio.nexlylab.dev/widget/pk_live_TWOJ_KLUCZ.js" defer></script>

To wszystko. Gotowy snippet — z już wpisanym kluczem — skopiujesz z panelu → Produkt → Instalacja. Motyw, język, zestaw bloków i pozostałe ustawienia pobierane są z serwera na podstawie klucza, więc zmiana konfiguracji nie wymaga dotykania Twojej strony.

Klucz podajesz raz — w adresie. To on mówi serwerowi, o który produkt chodzi, więc odpowiedź niesie wersję przypiętą do tego produktu zamiast domyślnej wersji kanału. Serwer wpisuje ten klucz do wydawanego pliku, dlatego nie trzeba go powtarzać w data-api-key. Klucz pk_live_… jest z założenia publiczny — i tak stoi w HTML-u Twojej strony — a o dostępie decydują wyłącznie sprawdzenia po stronie serwera (allowed_origins i kontrola klucza przy każdym żądaniu).

Starszy adres /widget.js (bez klucza) działa nadal i będzie działał zawsze — to właśnie ten adres wstawiają wtyczki WooCommerce i Shopify. Różnice są dwie: nie zna Twojego klucza, więc wymaga atrybutu data-api-key i nie da się pod nim przypiąć wersji per produkt. Jeżeli wklejasz snippet ręcznie, użyj formy z kluczem powyżej.

Gdy podasz oba, a będą różne, wygrywa klucz z adresu — to on zdecydował, którą wersję serwer wydał tej stronie — i loader powie o tym w konsoli.

Jeżeli korzystasz z własnej instancji Studio, podmień origin — ścieżka /widget/<klucz>.js jest taka sama na każdej instalacji i obsługuje ją sama platforma. Ten plik to tylko loader (bramka): którą wersję runtime'u pobrać i skąd, rozstrzyga serwer w chwili żądania, per klucz (katalog wydań w panelu superadmina). Sam runtime — UI, bloki, własny React — to osobna paczka @nexlylab/widget-runtime, której nikt nie instaluje: istnieje po to, żeby CDN (w naszym hostowanym wydaniu cdn.jsdelivr.net) miał co serwować. Jeżeli serwujesz runtime z własnego adresu, zarejestruj wydanie pod tym adresem w katalogu albo wskaż go w snippecie atrybutem data-cdn="https://twoj-cdn/…".

Dlaczego ten adres

Ten adres jest jedyną rekomendowaną ścieżką instalacji i celowo nie zawiera numeru wersji. Obie formy — /widget/<klucz>.js i starsze /widget.js — serwujemy z własnego origin z nagłówkami public, max-age=300, must-revalidate i silnym ETagiem (zmierzone na produkcji 2026-09-14: 200, 9 775 B, ok. 4,7 KB po gzipie) — przeglądarka odpytuje go co najwyżej raz na 5 minut, a między odpytaniami płaci tanie 304. Nowe wydanie widgetu dociera więc do Twoich odwiedzających w ciągu kilku minut, bez czyszczenia cache'u i bez trybu incognito.

npm i jsDelivr zostają hostem kodu. Te ~9,8 KB to wyłącznie drogowskaz: loader czyta z niego, którą wersję runtime'u pobrać, i ściąga ją z cdn.jsdelivr.net spod adresu przypiętego do konkretnej wersji paczki @nexlylab/widget-runtime — a więc immutable i cache'owanego na zawsze. Ciężki, kilkusetkilobajtowy kod widgetu nadal leci z sieci brzegowej jsDelivr; z naszego serwera idzie tylko ten mały wskaźnik, i tylko on odświeża się co 5 minut.

Dlatego nie wklejaj adresu z numerem wersji (…/@nexlylab/[email protected]/…). Taki adres jsDelivr odpowiada nagłówkiem max-age=31536000, immutable, co oznacza, że przeglądarka przez rok nie sprawdzi go ani razu — nawet przy wymuszonym odświeżeniu. Zamraża Cię to na jednym wydaniu do czasu ręcznej zmiany adresu w kodzie strony. Kopia v1.js publikowana w tej paczce na npm ma z tego samego powodu wskaźnik wpisany na stałe — na wersję runtime'u aktualną w chwili publikacji — bo jsDelivr nie ma serwera, który mógłby go rozstrzygać; numer tej paczki to numer bramki, nie runtime'u. Nie używaj też aliasu @latest: jest cache'owany niezależnie na każdym węźle jsDelivr przez 12 godzin, przez co potrafi wskazać loaderowi ścieżkę runtime'u, która jeszcze nie istnieje — widget wtedy nie wstaje w ogóle. Pełne pomiary i uzasadnienie: ADR 0001 — kontrakt dystrybucji widgetu.

Jak to wpływa na szybkość strony

Wklejony <script> pobiera tylko loader (ok. 5,75 KB gzip — 4,7 KB do wydania ECO-16734, które dodało odczyt notatki otwartego panelu, i ECO-16737, które dodało ofsety launchera sterowane przez stronę), który rysuje sam przycisk. Właściwy widget ściąga się dopiero, gdy odwiedzający najedzie na przycisk lub go kliknie, a poszczególne moduły — dopiero gdy są potrzebne. Ładowanie Twojej strony pozostaje nietknięte.

Opcje

Wszystkie są opcjonalne — domyślne wartości pochodzą z ustawień produktu.

| Atrybut | Wartości | Domyślnie | |---|---|---| | data-api-key | klucz pk_live_… / pk_test_… | brany z adresu; wymagany tylko na /widget.js | | data-theme | light, dark, system | system | | data-position | bottom-right, bottom-left | bottom-right | | data-preload | hover, idle, click | hover | | data-debug | obecność atrybutu włącza logi | wyłączone |

Diagnostykę można też włączyć bez zmiany kodu, dopisując ?nexly-debug=1 do adresu strony.

Sterowanie z Twojego kodu

window.Nexly istnieje natychmiast po wykonaniu snippetu — wywołania sprzed załadowania widgetu trafiają do kolejki i wykonują się później, więc nie trzeba niczego opóźniać.

<button onclick="Nexly('open')">Potrzebuję pomocy</button>

Dostępne polecenia: open, close, destroy.

Wymagania

Widget wymaga HTTPS, jeśli chcesz korzystać z rozmowy głosowej — mikrofon i WebRTC są przez przeglądarki dostępne wyłącznie w bezpiecznym kontekście. Czat tekstowy działa również po HTTP.

Domenę Twojej strony trzeba dodać w panelu do listy dozwolonych originów. Bez tego widget wczyta się, ale rozmowa zwróci błąd — komunikat w konsoli wskaże, gdzie to uzupełnić.

Licencja

MIT © NexlyLab