Події віджета в JavaScript: shukai:*

Для розробників, у коді: кожна CustomEvent shukai:* на window — життєвий цикл, повідомлення, голос, тизери, знахідки і скасовувані події дій, які хост може взяти на себе.

Віджет надсилає CustomEvent на window. Shukai.on("open", fn) — те саме, що window.addEventListener("shukai:open", fn).

Події дій — скасовувані

Для кожної дії у відповіді віджет надсилає дві події: shukai:action (для всіх дій) і shukai:action:<тип>. event.detail — об’єкт дії. Обидві скасовувані, і скасування будь-якої з них зараховується.

Тип	`detail`	`preventDefault()`
`navigate`	`{ type, url, label, source_id, referral_kind?, confirm? }`	віджет не переходить; переходить ваш роутер. Маячок `/followed` спрацьовує в обох випадках, тож лічильники переходів власника не залежать від того, хто виконав навігацію
`scroll`	`{ type: "scroll", direction }` — `down` · `up` · `top` · `bottom`	віджет не гортає; гортайте свій контейнер, і помічнику повідомляється, що хост це зробив
`handoff`	`{ type, targets, collect, source, target }` — надсилається, коли натиснуто кнопку контакту, `target` — натиснута	віджет нічого не відкриває і не надсилає маячок `/handoff/opened`; показуйте власний інтерфейс ескалації
власна подія власника	`{ type: <назва>, payload: { …поля } }`	нічого скасовувати — віджет на неї не діє; її малює ваша сторінка — Власні події
`close_widget` · `listen`	`{ type }`	лише сповіщення; віджет усе одно діє

Правила навколо navigate: автоматична навігація — лише в межах origin, у тій самій вкладці, лише http(s), щонайбільше одна за хід, а посилання на поточний URL ігнорується; клік на плашку підказки чи кнопку може відкрити зовнішній URL у новій вкладці; navigate, що прийшов під час голосової відповіді, чекає, поки озвучення закінчиться. Дія з прапорцем confirm: true не надсилається, доки відвідувач не погодиться, — вона притримана за чіпами, — а підтверджений перехід на інший origin нічого не робить. Кнопки дій при кліку надсилають ті самі події знову.

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);
});

Події життєвого циклу — не скасовувані

Подія	`detail`	Коли
`shukai:ready`	`{}`	змонтовано (і коли неактивний)
`shukai:open` · `shukai:close`	`{}`	компаньйон відкрився чи закрився
`shukai:conversation:new`	`{}`	почалася нова розмова
`shukai:conversation:enter` · `shukai:conversation:exit`	`{}`	голосова розмова почалася чи закінчилася
`shukai:message:sent`	`{ text }`	повідомлення відвідувача пішло
`shukai:message:received`	`{ text, sources, actions, navSuggestions }`	надійшла відповідь
`shukai:voice:speaking:start` · `:end`	`{}`	голосова відповідь почалася чи закінчилася; на кожен start рівно один end
`shukai:voice:listening:start` · `:stop`	`{}` · `{ text }`	мікрофон відкрився чи закрився, з остаточною розшифровкою на stop
`shukai:voice:transcript`	`{ text, isFinal }`	проміжна чи остаточна розшифровка
`shukai:voice:error`	`{ error }`	мікрофон не дозволено або розпізнавання не вдалося
`shukai:teaser:shown` · `shukai:teaser:dismissed`	`{}`	привітальна бульбашка на закритій кнопці
`shukai:suggestion:shown` · `:accepted` · `:dismissed`	`{ codes }`	проактивну знахідку запропоновано, клікнуто чи закрито — `codes` каже яку, тож хост може міряти частку відмов

Що хост зазвичай слухає

shukai:action:navigate — щоб маршрутизувати в SPA (Односторінкові додатки).
shukai:action:<ваша подія> — щоб намалювати результат у власному інтерфейсі.
shukai:message:received і shukai:open — для власної аналітики.
shukai:suggestion:* — щоб знати, чи піднята рука доречна.