JavaScript API віджета: window.Shukai

Для розробників, у коді: window.Shukai — кожен метод, які виклики ставляться в чергу до монтування, а які є станом, і як працюють надсилання повідомлення, вихід з акаунта та дії на сторінці.

window.Shukai встановлюється в момент виконання скрипта. Виклики до монтування віджета ставляться в чергу і виконуються по порядку, тож чекати на нього не треба:

Shukai.ready.then(() => {}); // виконується з API після монтування
Shukai.open();
Shukai.sendMessage("А в суботу ви доставляєте?");

Методи

Метод	Повертає	Вид	Що робить
`ready`	`Promise<api>`	—	виконується після монтування — і коли віджет неактивний (тоді кожен метод нічого не робить) або прихований на цій сторінці (він змонтується, коли вперше з’явиться)
`hide()` · `show()` · `isHidden()`	api · api · boolean	стан, ця сторінка	прибрати асистента зі сторінки й повернути; відкритий чат закривається, розмова зберігається; `show()` не скасовує правило сторінок власника чи «лише тим, хто увійшов»
`open()` · `close()` · `toggle()`	—	черга	відкрити чи закрити компаньйона; `open()` — єдиний вхід для headless-кнопки
`isOpen()`	boolean	одразу	`false` до монтування
`newConversation()`	—	черга	почати нову розмову; стара лишається в історії на пристрої
`sendMessage(text)`	—	черга	відкриває, потім надсилає. Відкриває в текстовому чаті, якщо запам’ятований режим відвідувача — не голосова розмова, тож відповідь не озвучується
`speak(text)`	—	черга	читає текст уголос; нічого не робить, якщо режим розмови вимкнений або звук не розблокований
`stopSpeaking()`	—	черга	відвідувач каже «помовч»: решта відповіді лишається беззвучною, а в розмові мікрофон знову відкривається
`startListening()` · `stopListening()`	—	черга	у живій розмові — репліка; інакше диктування в поле вводу — нічого не робить, якщо диктування вимкнене, навіть з увімкненим режимом розмови
`setPageActions(on)`	—	черга, не зберігається	дії на сторінці вимкнені чи увімкнені лише на це завантаження; не може увімкнути те, що власник вимкнув; вимкнення також зупиняє читання й прокрутку сторінки помічником
`setContext({ route, params })`	api	стан	оголошений екран для хеш-маршрутизації чи спільного шляху; викликати на кожній зміні маршруту — Односторінкові додатки
`getContext()`	`{ route, params }`	стан	останній оголошений контекст
`setUser(token)` · `clearUser()` · `getUser()`	api · api · рядок	стан, лише в пам’яті	токен користувача, що увійшов, передається як `{{user}}` — Ідентичність користувача
`clearHistory()`	—	черга	стирає всі розмови на цьому пристрої і запам’ятований режим; завершує живу розмову; перериває диктування; очищає поле вводу
`on(name, fn)` · `off(name, fn)`	api	—	тонкі обгортки над `window.addEventListener`; приймають `"open"` або `"shukai:open"`

Виклики з черги виконуються після монтування в порядку надходження. Виклики стану читаються заново на кожному повідомленні, тож перемагає найновіше значення, а виклик до монтування — не проблема.

Поки віджет прихований на сторінці — правилом сторінок власника, перемикачем «лише тим, хто увійшов» до setUser або вашим hide() — open(), toggle(), sendMessage(), speak() і startListening() нічого не роблять і не виконуються пізніше; консоль один раз пише, що саме його приховує. Решта працює, і clearHistory() також.

Немає expand, collapse чи presentation: виклик кидає TypeError. Поки що немає converse(text) — метод, що відкриває одразу голосову розмову і озвучує відповідь, у планах; сьогодні sendMessage дає ту саму відповідь і дію текстом.

Надсилання, вихід з акаунта і дії на сторінці

sendMessage надсилає текст як повідомлення відвідувача. Він відкриває віджет і надсилає текст; відповідь з’являється в чаті, а якщо відвідувач уже в голосовій розмові — ще й звучить. Голосова розмова починається, коли відвідувач натискає мікрофон помічника — він є там, де власник увімкнув голосові розмови і браузер може користуватися мікрофоном, — тож щоб запросити до неї, відкрийте віджет через open().

Вихід з акаунта: clearUser і clearHistory. clearUser() забуває токен користувача, тож помічник більше не отримує його даних. clearHistory() забуває розмови, збережені на цьому пристрої, — до семи днів. Під час виходу на комп’ютері, яким користуються й інші, викликайте обидва. Коли сесія просто закінчилася, достатньо clearUser(): за екраном та сама людина.

setPageActions діє на поточне завантаження сторінки. Дії на сторінці увімкнені на кожному завантаженні, де віджет працює зі сторінкою; setPageActions(false) вимикає їх для цього завантаження — помічник тоді не заповнює, не натискає, не читає й не прокручує сторінку, — а setPageActions(true) вмикає знову. Викликайте його на кожному завантаженні, де їх треба вимкнути.

Життєвий цикл

Shukai.on("open", () => analytics.track("assistant_opened"));
Shukai.on("message:received", (e) => console.log(e.detail.text, e.detail.sources));
Shukai.on("suggestion:dismissed", (e) => console.log("dismissed finding", e.detail.codes));

Кожна подія, яку надсилає віджет, — у Подіях.