Questa pagina è pubblicata in inglese e in ucraino; qui sotto c’è la versione inglese.
Widget events in JavaScript: shukai:*
For developers, in code: every shukai:* CustomEvent on window — lifecycle, messages, voice, teasers, findings, and the cancelable action events a host may take over.
The widget dispatches CustomEvents on window. Shukai.on("open", fn) is the same as
window.addEventListener("shukai:open", fn).
Action events — cancelable
For every action in an answer the widget dispatches two events: shukai:action (for all
actions) and shukai:action:<type>. event.detail is the action object. Both are cancelable,
and cancelling either one counts.
| Type | detail |
preventDefault() |
|---|---|---|
navigate |
{ type, url, label, source_id, referral_kind?, confirm? } |
the widget does not navigate; your router does. The /followed beacon fires either way, so the owner’s follow counts do not depend on who navigated |
scroll |
{ type: "scroll", direction } — down · up · top · bottom |
the widget does not scroll; scroll your own container, and the assistant is told the host handled it |
handoff |
{ type, targets, collect, source, target } — fired when a contact button is pressed, target the one pressed |
the widget opens nothing and sends no /handoff/opened beacon; run your own escalation UI |
| an owner’s custom event | { type: <name>, payload: { …fields } } |
nothing to cancel — the widget never acts on it; your page renders it — Custom events |
close_widget · listen |
{ type } |
notification only; the widget still acts |
Rules around navigate: automatic navigation is same-origin, same-tab, http(s) only, at most one
per turn, and a link to the current URL is ignored; a click on a suggestion plate or a button may
open an external URL in a new tab; a navigate arriving during a spoken answer waits until the
readout ends. An action flagged confirm: true is not dispatched until the visitor accepts —
it is held behind chips — and a confirmed navigate to another origin does nothing. Action buttons
re-emit the same events when clicked.
window.addEventListener("shukai:action:navigate", (e) => {
e.preventDefault();
router.push(new URL(e.detail.url).pathname);
});
window.addEventListener("shukai:action:show_products", (e) => {
renderProducts(e.detail.payload.products);
});Lifecycle events — not cancelable
| Event | detail |
When |
|---|---|---|
shukai:ready |
{} |
mounted (also when inactive) |
shukai:open · shukai:close |
{} |
the companion opened or closed |
shukai:conversation:new |
{} |
a fresh conversation started |
shukai:conversation:enter · shukai:conversation:exit |
{} |
a voice conversation started or ended |
shukai:message:sent |
{ text } |
the visitor’s message went out |
shukai:message:received |
{ text, sources, actions, navSuggestions } |
an answer arrived |
shukai:voice:speaking:start · :end |
{} |
a spoken answer started or finished; every start gets exactly one end |
shukai:voice:listening:start · :stop |
{} · { text } |
the microphone opened or closed, with the final transcript on stop |
shukai:voice:transcript |
{ text, isFinal } |
an interim or final transcript |
shukai:voice:error |
{ error } |
the microphone was denied or recognition failed |
shukai:teaser:shown · shukai:teaser:dismissed |
{} |
the greeting bubble on the closed launcher |
shukai:suggestion:shown · :accepted · :dismissed |
{ codes } |
a proactive finding was offered, clicked, or closed — codes names which, so a host can measure the dismissal rate |
What a host usually listens for
shukai:action:navigate— to route in an SPA (Single-page apps).shukai:action:<your event>— to draw a result in your own UI.shukai:message:receivedandshukai:open— for your own analytics.shukai:suggestion:*— to know whether the raised hand is welcome.