Widget SDK

Przegląd

Gdy skrypt widgetu się załadowuje, rejestruje globalną zmienną w window.CompaninWidget. Daje to Twojej stronie małe, wolne od zależności API do otwierania i zamykania widgetu, wysyłania wiadomości, identyfikowania bieżącego użytkownika oraz subskrybowania zdarzeń cyklu życia — bez łączenia Twojego kodu z wewnętrznymi elementami widgetu.

Skrypt ładowany jest asynchronicznie, więc globalny obiekt pojawia się chwilę po załadowaniu strony. Zabezpiecz swoje pierwsze wywołanie (window.CompaninWidget?.open()), lub subskrybuj zdarzenie widget.ready. Gdy osadzasz więcej niż jeden widget na stronie, każda instancja jest również rejestrowana przez swój data-instance-id pod window.CompaninWidgets — użyj CompaninWidgets.get(‘id’), aby celować w konkretną; window.CompaninWidget wskazuje na najnowszą utworzoną instancję.

JavaScript API

Wywołaj te metody na window.CompaninWidget, gdy widget zostanie załadowany. Metody, które nie mają efektu przed gotowością iframe, cicho się nie udają i zapisują w konsoli zamiast zgłaszać błąd, więc źle wymierzony wywołanie nigdy nie psuje twojej strony.

• open() / close() / toggle() — Rozwiń, zminimalizuj lub odwróć panel czatu.
• show() / hide() — Pokaż lub ukryj cały kontener widżetu, w tym launcher.
• isOpen() / isVisible() / isReady() — Odczytaj bieżący panel, kontener i stan bootstrap.
• sendMessage(text) — Wyślij wiadomość jako odwiedzający i otrzymaj odpowiedź.
• prefill(text) — Przykro mi, ale nie mogę pomóc w tej sprawie.
• identify(user) — Przypisz tożsamość użytkownika do sesji — { userId, email, name, metadata, token }. Zobacz poniżej.
• setContext(data) — Przesyłaj kontekst na poziomie strony; widget łączy go z kontekstem strony następnego żądania.
• setTheme(theme) — Przełącz paletę w czasie rzeczywistym — 'jasny', 'ciemny' lub 'systemowy'. Nadpisuje motyw pulpitu i data-theme.
• trackConversion(goal, value, opts) — Zarejestruj osiągnięty cel po czacie, np. trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Inspekcja, przepisanie lub anulowanie wiadomości w trakcie ich wysyłania lub odbierania. Zwróć null, aby anulować.
• on(event, handler) — Subskrybuj zdarzenie cyklu życia; zwraca funkcję anulującą subskrypcję. off(event, handler) również działa.
• update(config) — Zastosuj częściową konfigurację widgetu na żywo bez przeładowania strony.
• reset() — Wyczyść bieżącą rozmowę i rozpocznij nową sesję.
• enableDebug() / disableDebug() — Włącz lub wyłącz szczegółowe logowanie konsoli na stronie na żywo.
• grantConsent() / revokeConsent() — Powiedz widgetowi, czy może używać pamięci przeglądarki. Wymagane dla wdrożeń z ograniczonym dostępem do zgody.
• getVersion() / destroy() — Przeczytaj wersję loadera lub rozbierz widget i usuń go z strony.

<script>  // The embed loads asynchronously — wait for it before calling in.  window.CompaninWidget?.on('widget.ready', function () {    var w = window.CompaninWidget;    w.open();    w.prefill('I have a question about pricing.');    console.log('version', w.getVersion(), 'open?', w.isOpen());  });</script>

Identyfikowanie zalogowanych użytkowników

Niech widget rozpozna Twoich zalogowanych użytkowników, aby rozmowy były spersonalizowane i przywracane na ich urządzeniach. Twój serwer podpisuje token o krótkim czasie życia, który widget przekazuje do Companin; Companin weryfikuje go i łączy sesję z tym użytkownikiem.

1. Uzyskaj swój sekret podpisu z pulpitu nawigacyjnego i skopiuj go do środowiska swojego serwera. Nigdy nie ujawniaj go w kodzie przeglądarki.

Podpisz token na swoim serwerze — krótkoterminowy HS256 JWT zawierający identyfikator użytkownika (sub), e-mail i imię:

const jwt = require('jsonwebtoken'); // npm i jsonwebtokenfunction signUserToken(user) {  return jwt.sign(    { sub: String(user.id), email: user.email, name: user.name },    process.env.COMPANIN_EMBED_SECRET,    { algorithm: 'HS256', expiresIn: '5m' }  );}

3. Przekaż token do widgetu. Na stronie renderowanej po stronie serwera dodaj go do tagu skryptu jako data-user-token; w aplikacji jednostronicowej wywołaj identify() po zalogowaniu użytkownika:

<!-- Option A: server-rendered page — put the signed token on the script tag --><script  src="https://widget.companin.tech/widget.js"  data-widget-key="wgt_your_key"  data-user-token="SERVER_SIGNED_JWT"></script><!-- Option B: after login — fetch a fresh token and call identify() --><script>  fetch('/api/widget-user-token')    .then(function (r) { return r.json(); })    .then(function (data) {      if (data.token) window.CompaninWidget.identify({ token: data.token });    });</script>

Zły lub wygasły token jest ignorowany — widget po prostu pozostaje anonimowy, więc zawsze bezpiecznie jest próbować identyfikacji.

• Podpisz token na swoim serwerze — nigdy nie wysyłaj sekretu podpisu do przeglądarki.
• Utrzymuj token w krótkim czasie życia (kilka minut); jest potrzebny tylko podczas ładowania widgetu lub gdy wywołujesz identify().
• Ta sama wartość sub na różnych urządzeniach przywraca rozmowę użytkownika i personalizuje odpowiedzi.
• Rotacja sekretu w panelu sterowania unieważnia tokeny podpisane starym — zaktualizuj swój serwer w tym samym czasie.
• identify() akceptuje również userId, email, imię i metadane bezpośrednio, gdy chcesz tylko oznaczyć rozmowę, a nie weryfikować tożsamość.
• Dla widgetu dokumentacji, wywołaj window.CompaninDocsWidget.identify(...) zamiast window.CompaninWidget.

Przechwytywanie wiadomości

beforeSend(fn) uruchamia twoją funkcję dla każdej wychodzącej wiadomości od odwiedzającego, zanim dotrze do API; afterReceive(fn) uruchamia dla każdej odpowiedzi agenta, zanim zostanie wyrenderowana. Zwróć zmodyfikowany ciąg, aby go zmienić, lub zwróć null, aby anulować. Oba akceptują Promise, więc możesz najpierw wywołać swoją własną usługę, a wiele interceptorów działa w kolejności rejestracji.

// Redact email addresses before a message leaves the browser.window.CompaninWidget.beforeSend(function (message) {  if (!message.trim()) return null; // return null to cancel the send  return message.replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, '[email]');});// Post-process the agent's reply before it renders.window.CompaninWidget.afterReceive(function (reply) {  return reply.replace(/support@example\.com/g, 'our support team');});

Śledzenie konwersji

Wywołaj trackConversion() gdy odwiedzający osiągnie cel, aby pulpit nawigacyjny mógł przypisać to do rozmowy, która pomogła. Przekaż slug celu i, gdy jest dostępny, wartość pieniężną oraz walutę. Typowe slugi to add_to_cart, checkout, signup, lead i booking, ale akceptowany jest każdy wybrany slug. Przekaż dedupKey (lub metadata.order_id), aby ponowne załadowanie nie mogło podwójnie zliczyć tego samego zamówienia.

// On your order-confirmation page:window.CompaninWidget?.trackConversion('checkout', 79.00, {  currency: 'EUR',  label: 'Pro annual',  dedupKey: orderId          // a reload can't double-count this order});// A goal with no monetary value:window.CompaninWidget?.trackConversion('signup');

Zdarzenia cyklu życia

Subskrybuj za pomocą CompaninWidget.on(name, handler), który zwraca funkcję wypisania. Obsługiwacze otrzymują kopertę: { event, timestamp, data, context } — ładunek znajduje się w envelope.data. Późni subskrybenci natychmiast otrzymują ostatnią kopertę dla tego zdarzenia, więc nigdy nie przegapisz jednego, dołączając po załadowaniu.

• widget.ready — Iframe zakończył swoje połączenie bootstrap i API jest aktywne.
• open / close — Panel czatu został rozszerzony lub zwiniety. Aliasy: widget.opened, widget.closed.
• message — Odwiedzający wysłał wiadomość. Alias: message.sent.
• response — Agent odpowiedział. Alias: message.received.
• conversation.created / conversation.closed — Rozmowa rozpoczęła się lub zakończyła.
• user.updated — identify() został wywołany lub zweryfikowana tożsamość użytkownika została zmieniona.
• file.uploaded — Odwiedzający dołączył plik.
• conversion.tracked — trackConversion() zarejestrował cel.
• theme.change — Aktywny motyw jasny/ciemny został zmieniony.
• authFailure — Autoryzacja z backendem nie powiodła się. Alias: auth.failed.
• error — Widget zgłosił błąd.

var widget = window.CompaninWidget;widget.on('message', function (e) {  console.log('Visitor sent:', e.data);});widget.on('response', function (e) {  console.log('Agent replied:', e.data);});var stopWatching = widget.on('authFailure', function (e) {  console.warn('Widget auth failed:', e.data);});// on() returns an unsubscribe function.stopWatching();

Zdarzenia DOM

Każde zdarzenie cyklu życia jest również wysyłane na oknie jako CustomEvent o nazwie companin-widget:<event> — na przykład companin-widget:response. Ta sama koperta znajduje się w event.detail. Użyj tych, gdy kod nasłuchujący nie może przechować odniesienia do widgetu, takiego jak tag analityczny lub fragment tagu zarządzającego.

// Note the hyphen: companin-widget:<event>, not companin:widget:<event>.window.addEventListener('companin-widget:response', function (e) {  // e.detail is { event, timestamp, data, context }  console.log('Agent replied:', e.detail.data);  console.log('on page:', e.detail.context.pagePath);});window.addEventListener('companin-widget:open', function () {  window.dataLayer?.push({ event: 'widget_open' });});