Weboldal-widgetek

Ágyazd be az AI hangügynököd bármilyen weboldalra, hogy a látogatók közvetlenül a böngészőből indíthassanak hangbeszélgetést. A Widgets lap beágyazási kódokat, testreszabási lehetőségeket és domain-biztonsági beállításokat kínál.

A callback widgetet keresed?

A Callback Widget nagyon másképp működik, mint az ezen az oldalon lévő widgetek — ahelyett, hogy böngészős hanghívást indítana, begyűjti a látogató telefonszámát, és az ügynököd visszahívja őt. Lásd a dedikált Callback Widget oldalt.

A Hanc.AI négy böngészős widget-típust kínál, plusz egy külön Callback Widgetet a telefonos visszahívásokhoz:

Widget	Tag neve	Leírás	Mire a legjobb
Floating Widget	`hanc-ai-floating-call`	Lebegő gomb, amely az oldalad felett úszik	Mindig látható felhívás cselekvésre
Pill Widget	`hanc-ai-pill-call`	Kompakt, tabletta alakú gomb a tartalomba ágyazva	Minimális helyfoglalás egy meglévő elrendezésen belül
Pill Floating Widget	`hanc-ai-pill-floating-call`	Ugyanaz a kompakt tabletta alak, mint a Pill, de az oldallal együtt lebeg, mint a Floating widget	Ha tabletta esztétikát szeretnél, amely görgetés közben követi a látogatót
Inline Widget	`hanc-ai-inline-call`	Teljes méretű hívógomb az oldal tartalmába ágyazva	Dedikált „Beszéljen velünk" szekciók
Callback Widget	`hanc-ai-callback`	Telefonszám-űrlap; az ügynök visszahívja a látogatót	Lead-gyűjtő oldalak, magas szándékú landing oldalak — lásd Callback Widget

Közös attribútumok

Minden widget-típus támogatja ezeket az alapvető attribútumokat:

Attribútum	Kötelező	Leírás	Alapértelmezett
`agent-id`	Igen	Az ügynököd egyedi azonosítója	—
`voice-service-url`	Nem	A hangszolgáltatás URL-jének felülírása	Automatikusan felismerve
`api-base-url`	Nem	Az API alap-URL-jének felülírása	Automatikusan felismerve

Megjelenítési attribútumok

Attribútum	Leírás	Értékek	Alapértelmezett
`position`	A widget pozíciója az oldalon	`bottom-right`, `bottom-left`, `top-right`, `top-left`, `static`	`bottom-right`
`size`	A widget mérete pixelben	Szám	`120`
`theme`	Színtéma neve	Lásd Színtémák	`default`

Gombszöveg-attribútumok

Attribútum	Leírás	Alapértelmezett
`button-start-text`	Az inaktív gombon megjelenő szöveg	`"Call"`
`button-connecting-text`	A csatlakozás közben megjelenő szöveg	`"Connecting..."`
`button-end-text`	Aktív hívás közben megjelenő szöveg	—

Feltételek-attribútumok

Attribútum	Leírás	Alapértelmezett
`terms-enabled`	Hozzájárulási párbeszédpanel engedélyezése hívás előtt	`false`
`terms-content`	Markdown-formátumú hozzájárulási szöveg	`""`
`terms-url`	Link a Felhasználási feltételek oldaladra	`"https://hanc.ai/terms"`
`privacy-url`	Link az Adatvédelmi szabályzat oldaladra	`"https://hanc.ai/privacy"`

információ

A HTML-elemen beállított Terms-attribútumokat felülírják az ügynök API-ból lekért widget-beállításai, hacsak a skip-fetch értéke nincs true-ra állítva.

Hang-attribútumok

Attribútum	Leírás	Alapértelmezett
`sound-enabled`	Hívás eleji/végi hangok engedélyezése	`true`
`sound-volume`	A hangeffektus hangereje	`0.25`
`sound-preset`	Hang-előbeállítás azonosítója	`"1"`

Színtémák

Szabd testre a widget megjelenését 11 beépített színtémával:

Téma	Érték
Default	`default`
Purple	`purple`
Blue	`blue`
Cyan	`cyan`
Emerald	`emerald`
Amber	`amber`
Tangerine	`tangerine`
Rose	`rose`
Ember	`ember`
Black	`black`
White	`white`

Minden témának van sötét és világos változata is. Állítsd be a témát a beágyazási kódban a theme attribútummal, vagy konfiguráld az ügynök widget-beállításaiban.

Beágyazási példák

<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>

<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>

<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>

<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>

Widget-verzió rögzítése

A fenti szkript-URL mindig a legfrissebb kiadott widgetet tölti be — az oldalad automatikusan megkapja a fejlesztéseket, és a @latest az alapértelmezett, ha nincs verzió megadva. Ha egy rögzített kiadáshoz szeretnél kötődni, rögzítsd explicit módon a kívánt verzió hozzáfűzésével, pl. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.

A widgetek eseményeket bocsátanak ki, amelyekre JavaScriptben figyelhetsz:

Esemény	Leírás
`status-changed`	Akkor aktiválódik, amikor a hívás állapota megváltozik
`connecting`	A hívás létrejön
`connected`	A hívás aktív
`idle`	Nincs aktív hívás
`error`	Hiba történt
`audio-track`	Távoli hangsáv fogadva (vizualizációhoz)
`local-audio-track`	Helyi mikrofon hangsáv (vizualizációhoz)
`microphone-enabled`	A mikrofon engedélyezve lett
`microphone-disabled`	A mikrofon letiltva lett
`call-start`	Akkor aktiválódik, amikor egy hívás sikeresen elindul
`call-end`	Akkor aktiválódik, amikor a hívás véget ér

Példa: események figyelése

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

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

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

Böngészőből indított hívás közben az ügynök megkérheti a webhelyét, hogy nyisson meg egy oldalt – „mutatom az árakat” –, és a látogató ezt látja anélkül, hogy megszakítaná a beszélgetést.

A döntés az oldaláé marad. Az ügynök kérést küld, az Ön kódja dönti el, mit jelent. URL megnyitása, fülváltás, görgetés egy szakaszhoz, harmonika kinyitása – mind érvényes válasz.

Három lépés kell hozzá, és egyik sem működik önmagában.

1. lépés – Mondja meg az ügynöknek, milyen oldalak vannak

Az ügynök nem látja a webhely szerkezetét. Csak olyan útvonalat kér, amit Ön adott meg neki – sorolja fel őket az ügynök promptjában vagy a tudásbázisban:

Webhelyünk oldalai:
/pricing — csomagok és árak
/contact — kapcsolatfelvételi űrlap és telefonszám
/product/crm — a CRM

E lépés nélkül az ügynöknek nincs mit kérnie, így meg sem próbálja.

2. lépés – Kezelje a kérést az oldalán

Adja hozzá egyszer, bárhová a widget szkriptje után. Az esemény felbuborékol az oldalon, így a document jó hely a figyelésre:

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

  if (type === 'navigate') {
    // SPA: útválasztás újratöltés nélkül — a hívás folytatódik.
    router.push(payload.path);

    // Klasszikus webhely: nyisson egy második fület, így ez (és a hívás) életben marad.
    // window.open(payload.path, '_blank');

    event.preventDefault();   // ← ezzel jelzi az ügynöknek, hogy kezelte
  }
});
</script>

A teljes újratöltés megszakítja a hívást

A hívás ebben az oldalban él. A window.location.href = … eldobja a dokumentumot, és a beszélgetés vele megy — a látogatót mondat közben szakítja meg. Ha van routere, navigáljon kliensoldalon; ha nincs, nyissa meg az oldalt új fülön. Nincs újracsatlakozás: az újratöltést semmi sem éli túl.

A preventDefault() nem opcionális

Ez az egyetlen módja annak, hogy azt mondja: „megoldottam”. Nélküle az ügynök azt kapja vissza, hogy a webhely nem támogatja a navigációt: a hívás hátralévő részében nem próbálkozik többé, és inkább elmondja, hova kell kattintani. A konzolban semmi sem jelenik meg – az oldal egyszerűen úgy néz ki, mintha figyelmen kívül hagyta volna a kérést, mert így is tett.

3. lépés – Próbálja ki

Hívja fel az ügynökét a webhelyről, és kérjen egy oldalt név szerint. Két dolognak kell történnie: az oldal megnyílik, és az ügynök olyasmit mond, hogy „itt vannak az árak”, nem pedig azt, hogy „megtalálja a menüben”.

Válasz az ügynöknek adatokkal

Néhány parancs kérdés, nem utasítás. Ugyanúgy érkeznek, de respond()-dal kell válaszolni rájuk:

Parancs	Mit kérdez az ügynök	Mivel válaszol
`navigate`	„nyisd meg ezt az útvonalat”	semmivel – elég a `preventDefault()`
`page_context`	„mit néz éppen a látogató?”	bármi hasznossal: útvonal, cím, termék
`cart_state`	„mi van a kosarában?”	tételek, végösszeg, pénznem

<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>

A preventDefault() után nagyjából egy másodperce van válaszolni – egy await belefér, egy lassú API-hívás nem. Azzal válaszoljon, ami már kéznél van.

Mit kérhet és mit nem kérhet az ügynök

Csak a saját webhelyén belüli útvonalakat. Az útvonalnak / jellel kell kezdődnie. Bármi, ami elhagyhatná a domainjét – //evil.com, https://…, fordított perjelek –, elutasításra kerül, mielőtt elérné az oldalt. Az ügynök nem küldheti a látogatóit máshová.
Csak böngészőhívásoknál. Telefonhívás közben nincs mit megnyitni, ezért ott ezek a parancsok nem léteznek.
Egy elutasítás elég. Ha az oldala nem erősíti meg az első kérést, az ügynök a hívás hátralévő részében nem kérdez többé. Nem próbálkozik újra, és – ami fontosabb – nem mondja a látogatónak, hogy megnyitott valamit, amit nem nyitott meg.

Nem történik semmi?

Naplózzon minden parancsot, mielőtt szűrné: document.addEventListener('agent-command', e => console.log(e.detail)). Ha látja a navigate-et a konzolban, az ügynök megtette a magáét, és a preventDefault() vagy a saját kezelője hiányzik. Ha semmit sem lát, az ügynöknek soha nem mondták, hogy létezik ez az útvonal – vissza az 1. lépéshez.

Technikai követelmények

A widgetekhez a látogató böngészőjének támogatnia kell a következőket:

WebGL 2.0 — a megjelenítéshez
Web Audio API — a hangfeldolgozáshoz
WebRTC — a valós idejű hangkommunikációhoz

Minden modern böngésző (Chrome, Firefox, Safari, Edge) támogatja ezeket a technológiákat.

Domain-korlátozások

Szabályozd, mely weboldalak ágyazhatják be az ügynök-widgetedet.

Mindig engedélyezett domainek

A következő domainek mindig engedélyezettek, a konfigurációtól függetlenül:

hanc.ai (és aldomainek)
hanc.me (és aldomainek)
localhost

Minden domain engedélyezése

Alapértelmezés szerint a widgeted bármely weboldalon beágyazható. Kapcsold be az „Allow all domains" opciót a widget-beállításokban ennek korlátozásához.

Korlátozás adott domainekre

Korlátozás esetén add hozzá minden engedélyezni kívánt domaint:

Add meg a domainneveket https:// nélkül (pl. example.com)
Az aldomainek külön bejegyzést igényelnek (pl. www.example.com, shop.example.com)
Portok is megadhatók (pl. localhost:3000)
Legfeljebb 50 domain vehető fel a fehérlistára

Biztonság

Éles ügynököknél korlátozd a widgeteket a saját domainjeidre, hogy megakadályozd a jogosulatlan beágyazást.

Felhasználási feltételek

Engedélyezz egy hozzájárulási párbeszédpanelt, mielőtt a hívók beszélgetést kezdhetnének.

Konfiguráció

Beállítás	Leírás
Enable Terms	A feltételek párbeszédpanel be-/kikapcsolása
Terms Content	A felhasználóknak megjelenített Markdown-formátumú hozzájárulási szöveg (max. 5 000 karakter)
Terms URL	Link a teljes Felhasználási feltételek oldaladra
Privacy URL	Link az Adatvédelmi szabályzat oldaladra

Ha engedélyezve van:

A felhasználók hozzájárulási párbeszédpanelt látnak a hívás megkezdése előtt
A folytatáshoz az „Agree" gombra kell kattintaniuk
A hozzájárulás helyileg tárolódik a böngészőben
A Reset Consent gomb törli a tárolt hozzájárulást teszteléshez

Tartalom formázása

A feltételek tartalma Markdown formázást támogat:

Használj #### jelet fejlécekhez
Használj **bold** jelet a kiemeléshez
Használj sortöréseket az olvashatóság érdekében

Kapcsolódó

Callback Widget — Telefonos visszahívások azoknak a látogatóknak, akik inkább nem beszélnének a böngészőben
AI hangügynökök áttekintése
Beállítások — Ügynök-beállítások, beleértve a widget-konfigurációt
Integrációk — API-kulcsok és telefonszám-beállítás

Weboldal-widgetek

Widget-típusok

Közös attribútumok

Megjelenítési attribútumok

Gombszöveg-attribútumok

Feltételek-attribútumok

Hang-attribútumok

Színtémák

Beágyazási példák

Floating Widget

Floating Widget témával és pozícióval

Pill Widget

Inline Widget

Widget-események

Példa: események figyelése

Engedje, hogy az ügynök oldalakat nyisson meg

1. lépés – Mondja meg az ügynöknek, milyen oldalak vannak

2. lépés – Kezelje a kérést az oldalán

3. lépés – Próbálja ki

Válasz az ügynöknek adatokkal

Mit kérhet és mit nem kérhet az ügynök

Technikai követelmények

Domain-korlátozások

Mindig engedélyezett domainek

Minden domain engedélyezése

Korlátozás adott domainekre

Felhasználási feltételek

Konfiguráció

Tartalom formázása

Kapcsolódó

Widget-típusok​

Közös attribútumok​

Megjelenítési attribútumok​

Gombszöveg-attribútumok​

Feltételek-attribútumok​

Hang-attribútumok​

Színtémák​

Beágyazási példák​

Floating Widget​

Floating Widget témával és pozícióval​

Pill Widget​

Inline Widget​

Widget-események​

Példa: események figyelése​

Engedje, hogy az ügynök oldalakat nyisson meg​

1. lépés – Mondja meg az ügynöknek, milyen oldalak vannak​

2. lépés – Kezelje a kérést az oldalán​

3. lépés – Próbálja ki​

Válasz az ügynöknek adatokkal​

Mit kérhet és mit nem kérhet az ügynök​

Technikai követelmények​

Domain-korlátozások​

Mindig engedélyezett domainek​

Minden domain engedélyezése​

Korlátozás adott domainekre​

Felhasználási feltételek​

Konfiguráció​

Tartalom formázása​

Kapcsolódó​

Widget-típusok

Közös attribútumok

Megjelenítési attribútumok

Gombszöveg-attribútumok

Feltételek-attribútumok

Hang-attribútumok

Színtémák

Beágyazási példák

Floating Widget

Floating Widget témával és pozícióval

Pill Widget

Inline Widget

Widget-események

Példa: események figyelése

Engedje, hogy az ügynök oldalakat nyisson meg

1. lépés – Mondja meg az ügynöknek, milyen oldalak vannak

2. lépés – Kezelje a kérést az oldalán

3. lépés – Próbálja ki

Válasz az ügynöknek adatokkal

Mit kérhet és mit nem kérhet az ügynök

Technikai követelmények

Domain-korlátozások

Mindig engedélyezett domainek

Minden domain engedélyezése

Korlátozás adott domainekre

Felhasználási feltételek

Konfiguráció

Tartalom formázása

Kapcsolódó