Przejdź do głównej zawartości
DocumentationAPI ReferenceVideo Tutorials

Widgety witryny

Osadź swojego agenta głosowego na dowolnej stronie, aby odwiedzający mogli rozpocząć rozmowę głosową bezpośrednio z przeglądarki. Zakładka Widgety dostarcza kody osadzania, opcje dostosowywania oraz ustawienia zabezpieczeń domeny.

Szukasz widgetu oddzwaniania?

Widget oddzwaniania działa bardzo inaczej niż widgety na tej stronie — zamiast rozpoczynać rozmowę głosową w przeglądarce, zbiera numer telefonu odwiedzającego i sprawia, że Twój agent oddzwania. Zobacz dedykowaną stronę Widget oddzwaniania.

Typy widgetów​

Hanc.AI oferuje cztery typy widgetów w przeglądarce oraz osobny Widget oddzwaniania dla oddzwaniań telefonicznych:

WidgetNazwa znacznikaOpisNajlepszy dla
Widget pływającyhanc-ai-floating-callPrzycisk-kula, który unosi się nad stronąZawsze widoczne wezwanie do działania
Widget pigułkahanc-ai-pill-callKompaktowy przycisk w kształcie pigułki umieszczony inline w treściMinimalny ślad wewnątrz istniejącego układu
Widget pływająca pigułkahanc-ai-pill-floating-callTen sam kompaktowy kształt pigułki co Pigułka, ale unosi się ze stroną jak widget PływającyGdy chcesz estetyki pigułki, która podąża za odwiedzającym podczas przewijania
Widget inlinehanc-ai-inline-callPrzycisk połączenia pełnego rozmiaru osadzony w treści stronyDedykowane sekcje „Porozmawiaj z nami"
Widget oddzwanianiahanc-ai-callbackFormularz numeru telefonu; agent oddzwania do odwiedzającegoStrony generujące leady, strony docelowe o wysokiej intencji — zobacz Widget oddzwaniania

Wspólne atrybuty​

Wszystkie typy widgetów obsługują te podstawowe atrybuty:

AtrybutWymaganyOpisDomyślnie
agent-idTakUnikalny identyfikator Twojego agenta—
voice-service-urlNieNadpisz URL usługi głosowejWykrywany automatycznie
api-base-urlNieNadpisz bazowy URL APIWykrywany automatycznie

Atrybuty wyświetlania​

AtrybutOpisWartościDomyślnie
positionPozycja widgetu na stroniebottom-right, bottom-left, top-right, top-left, staticbottom-right
sizeRozmiar widgetu w pikselachLiczba120
themeNazwa motywu kolorystycznegoZobacz Motywy kolorystycznedefault

Atrybuty tekstu przycisku​

AtrybutOpisDomyślnie
button-start-textTekst pokazywany na bezczynnym przycisku"Call"
button-connecting-textTekst pokazywany podczas łączenia"Connecting..."
button-end-textTekst pokazywany podczas aktywnego połączenia—

Atrybuty regulaminu​

AtrybutOpisDomyślnie
terms-enabledWłącz okno zgody przed połączeniemfalse
terms-contentTekst zgody sformatowany w Markdown""
terms-urlLink do Twojej strony Regulaminu"https://hanc.ai/terms"
privacy-urlLink do Twojej strony Polityki prywatności"https://hanc.ai/privacy"
informacja

Atrybuty regulaminu ustawione na elemencie HTML są nadpisywane przez ustawienia widgetu agenta pobierane z API, chyba że skip-fetch jest ustawione na true.

Atrybuty dźwięku​

AtrybutOpisDomyślnie
sound-enabledWłącz dźwięki rozpoczęcia/zakończenia połączeniatrue
sound-volumeGłośność efektów dźwiękowych0.25
sound-presetIdentyfikator presetu dźwięku"1"

Motywy kolorystyczne​

Dostosuj wygląd widgetu za pomocą 11 wbudowanych motywów kolorystycznych:

MotywWartość
Defaultdefault
Purplepurple
Blueblue
Cyancyan
Emeraldemerald
Amberamber
Tangerinetangerine
Roserose
Emberember
Blackblack
Whitewhite

Każdy motyw ma warianty ciemny i jasny. Ustaw motyw za pomocą atrybutu theme w kodzie osadzenia lub skonfiguruj go w ustawieniach widgetu agenta.

Przykłady osadzenia​

Widget pływający​

<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Widget pływający z motywem i pozycją​

<hanc-ai-floating-call
  agent-id="YOUR_AGENT_ID"
  theme="emerald"
  position="bottom-left"
  size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Widget pigułka​

<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Widget inline​

<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Przypinanie wersji widgetu

Powyższy URL skryptu zawsze ładuje najnowszy wydany widget — Twoja witryna automatycznie pobiera ulepszenia, a @latest jest domyślne, gdy nie podano wersji. Jeśli musisz zablokować się do stałego wydania, przypnij jawnie, dołączając żądaną wersję, np. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.

Zdarzenia widgetu​

Widgety emitują zdarzenia, których możesz nasłuchiwać w JavaScript:

ZdarzenieOpis
status-changedUruchamiane, gdy zmienia się status połączenia
connectingPołączenie jest nawiązywane
connectedPołączenie jest aktywne
idleBrak aktywnego połączenia
errorWystąpił błąd
audio-trackOdebrano zdalną ścieżkę audio (do wizualizacji)
local-audio-trackLokalna ścieżka audio mikrofonu (do wizualizacji)
microphone-enabledMikrofon został włączony
microphone-disabledMikrofon został wyłączony
call-startUruchamiane, gdy połączenie rozpocznie się pomyślnie
call-endUruchamiane, gdy połączenie się kończy

Przykład: nasłuchiwanie zdarzeń​

const widget = document.querySelector('hanc-ai-floating-call');

widget.addEventListener('call-start', () => {
  console.log('Call started');
});

widget.addEventListener('call-end', () => {
  console.log('Call ended');
});

Jak pozwolić agentowi otwierać strony​

Podczas rozmowy z przeglądarki agent może poprosić Twoją witrynę o otwarcie strony — „pokażę cennik” — a odwiedzający widzi to, nie przerywając rozmowy.

Decyduje Twoja strona. Agent wysyła prośbę, a Twój kod ustala, co ona znaczy. Otwarcie adresu, przełączenie zakładki, przewinięcie do sekcji, rozwinięcie akordeonu — wszystko to poprawne odpowiedzi.

Potrzebne są trzy kroki i żaden nie działa osobno.

Krok 1 — Powiedz agentowi, jakie strony istnieją​

Agent nie widzi mapy Twojej witryny. Prosi wyłącznie o ścieżki, które mu podałeś — wypisz je w promptcie agenta lub w bazie wiedzy:

Strony naszej witryny:
/pricing — plany i ceny
/contact — formularz kontaktowy i telefon
/product/crm — CRM

Bez tego kroku agent nie ma o co prosić i nawet nie spróbuje.

Krok 2 — Obsłuż prośbę na swojej stronie​

Dodaj to raz, gdziekolwiek po skrypcie widżetu. Zdarzenie bąbelkuje w górę strony, więc document jest dobrym miejscem:

<script>
document.addEventListener('agent-command', (event) => {
  const { type, payload } = event.detail;

  if (type === 'navigate') {
    // SPA: nawigacja bez przeładowania — rozmowa trwa dalej.
    router.push(payload.path);

    // Klasyczna witryna: otwórz drugą kartę, ta (i rozmowa) pozostanie żywa.
    // window.open(payload.path, '_blank');

    event.preventDefault();   // ← to mówi agentowi „obsłużone”
  }
});
</script>
Pełne przeładowanie strony kończy rozmowę

Rozmowa żyje w tej stronie. window.location.href = … usuwa dokument, a rozmowa znika razem z nim — odwiedzający zostaje przerwany w pół zdania. Jeśli masz router, nawiguj po stronie klienta; w przeciwnym razie otwórz stronę w nowej karcie. Nie ma ponownego łączenia: przeładowania nie przetrwa nic.

preventDefault() nie jest opcjonalne

To jedyny sposób, by powiedzieć „zajęłem się tym”. Bez niego agent dowiaduje się, że witryna nie obsługuje nawigacji: przestaje próbować do końca rozmowy i wraca do opisywania, gdzie kliknąć. W konsoli nic się nie pojawi — strona po prostu wygląda, jakby zignorowała prośbę, bo ją zignorowała.

Krok 3 — Sprawdź​

Zadzwoń do swojego agenta z witryny i poproś o stronę po nazwie. Powinny wydarzyć się dwie rzeczy: strona się otwiera, a agent mówi coś w rodzaju „oto ceny” zamiast „znajdzie je Pan w menu”.

Jak odpowiadać agentowi danymi​

Niektóre polecenia to pytania, nie instrukcje. Przychodzą tak samo, ale odpowiada się przez respond():

PolecenieO co pyta agentCzym odpowiadasz
navigate„otwórz tę ścieżkę”niczym — wystarczy preventDefault()
page_context„na co patrzy odwiedzający?”czymkolwiek przydatnym: ścieżka, tytuł, produkt
cart_state„co ma w koszyku?”pozycje, sumy, waluta
<script>
document.addEventListener('agent-command', (event) => {
  const { type, respond } = event.detail;

  if (type === 'page_context') {
    event.preventDefault();
    respond({ path: location.pathname, title: document.title });
  }
});
</script>

Po preventDefault() masz około sekundy na odpowiedź — await jest w porządku, wolne wywołanie API już nie. Odpowiadaj tym, co i tak już masz.

O co agent może, a o co nie może prosić​

  • Tylko ścieżki w obrębie Twojej witryny. Ścieżka musi zaczynać się od /. Wszystko, co mogłoby wyprowadzić poza Twoją domenę — //evil.com, https://…, ukośniki wsteczne — jest odrzucane, zanim dotrze do strony. Agent nie wyśle Twoich odwiedzających gdzie indziej.
  • Tylko rozmowy z przeglądarki. Podczas rozmowy telefonicznej nie ma czego otwierać, więc tam te polecenia nie istnieją.
  • Jedna odmowa wystarczy. Jeśli Twoja strona nie potwierdzi pierwszej prośby, agent przestaje pytać do końca rozmowy. Nie spróbuje ponownie i — co ważniejsze — nie powie odwiedzającemu, że coś otworzył, skoro nie otworzył.
Nic się nie dzieje?

Loguj każde polecenie zanim je odfiltrujesz: document.addEventListener('agent-command', e => console.log(e.detail)). Jeśli widzisz w konsoli navigate, agent zrobił swoje, a brakuje preventDefault() albo Twojej obsługi. Jeśli nie widzisz nic, agentowi nigdy nie powiedziano, że taka ścieżka istnieje — wróć do kroku 1.

Wymagania techniczne​

Widgety wymagają, aby przeglądarka odwiedzającego obsługiwała:

  • WebGL 2.0 — do renderowania
  • Web Audio API — do przetwarzania dźwięku
  • WebRTC — do komunikacji głosowej w czasie rzeczywistym

Wszystkie nowoczesne przeglądarki (Chrome, Firefox, Safari, Edge) obsługują te technologie.

Ograniczenia domeny​

Kontroluj, które strony mogą osadzać widget Twojego agenta.

Zawsze dozwolone domeny​

Następujące domeny są zawsze dozwolone niezależnie od konfiguracji:

  • hanc.ai (i subdomeny)
  • hanc.me (i subdomeny)
  • localhost

Zezwól na wszystkie domeny​

Domyślnie Twój widget może być osadzany na dowolnej stronie. Przełącz „Zezwól na wszystkie domeny" w ustawieniach widgetu, aby to ograniczyć.

Ogranicz do konkretnych domen​

Gdy ograniczone, dodaj każdą domenę, która powinna być dozwolona:

  • Wprowadzaj nazwy domen bez https:// (np. example.com)
  • Subdomeny wymagają osobnych wpisów (np. www.example.com, shop.example.com)
  • Można określić porty (np. localhost:3000)
  • Maksymalnie 50 domen można umieścić na białej liście
Bezpieczeństwo

Dla agentów produkcyjnych ogranicz widgety do własnych domen, aby zapobiec nieautoryzowanemu osadzaniu.

Regulamin​

Włącz okno zgody, zanim dzwoniący będą mogli rozpocząć rozmowę.

Konfiguracja​

UstawienieOpis
Włącz regulaminPrzełącznik okna regulaminu wł./wył.
Treść regulaminuTekst zgody sformatowany w Markdown pokazywany użytkownikom (maks. 5 000 znaków)
URL regulaminuLink do Twojej pełnej strony Regulaminu
URL prywatnościLink do Twojej strony Polityki prywatności

Gdy włączone:

  • Użytkownicy widzą okno zgody przed rozpoczęciem połączenia
  • Muszą kliknąć „Zgadzam się", aby kontynuować
  • Zgoda jest przechowywana lokalnie w przeglądarce
  • Przycisk Resetuj zgodę czyści zapisaną zgodę do testów

Formatowanie treści​

Treść regulaminu obsługuje formatowanie Markdown:

  • Użyj #### dla nagłówków
  • Użyj **bold** dla wyróżnienia
  • Używaj podziałów wierszy dla czytelności

Powiązane​