Власні події: результат на вашій сторінці

Для розробників, у коді: дія, яку малює ваша сторінка — поля події, як її отримує хост, зв'язок інструмент→подія, що викликає її детерміновано, і перемикачі тизера та згоди.

Власна подія — це дія, яку помічник надсилає, а ваша сторінка малює: відкрити картку товару, відфільтрувати список, показати модальне вікно. Помічник ніколи не малює ваш інтерфейс; він просить ваш. Один слухач на вашій сторінці, написаний раз.

Власні події входять у тариф Growth і вищі.

У панелі: Інструменти → Нова подія (Інструменти та події). Ця сторінка — та сама подія поле за полем і слухач на вашій сторінці.

Визначте її в панелі

Поле	Що це
`name`	slug, унікальний у межах сайту — стає `type` дії, і ваша сторінка слухає `shukai:action:<name>`
`description`	коли її надсилати — єдиний сигнал моделі, коли подію ініціює модель
`fields`	схема корисного навантаження: `{ name, type, description, required }`, тип `string` · `number` · `integer` · `boolean` · `array`, до 20
`suppress_navigate`	відкинути будь-який `navigate` з того самого ходу — ваш інтерфейс показує результат, помічник не має ще й переводити відвідувача
`teaser`	закінчити хід коротким «знайшов — показую» замість повної відповіді
`confirm`	спитати відвідувача перед надсиланням; дія приходить із `confirm: true`, віджет притримує її за чіпами, а сервер оцінює відповідь у будь-яких словах
`scope`, `screens`, `agent`	як в інструментів: кожен екран або лише екрани, що її називають; один агент або всі

Отримайте її на сторінці

window.addEventListener("shukai:action:show_products", (e) => {
  const { products } = e.detail.payload;
  renderProductGrid(products);
});

event.detail — це { type: "show_products", payload: { …поля } }; shukai:action теж спрацьовує, для кожної дії. Це «надіслав і забув»: моделі нічого не повертається, і скасовувати нічого. Блок Симуляція на формі події надсилає одну з прикладами значень, щоб ви побачили, що отримує ваш слухач, і друкує фрагмент слухача для копіювання.

Два способи, якими спрацьовує подія

Від моделі. Подія пропонується моделі як інструмент; вона надсилає її, коли каже опис, і лише коли можна заповнити кожне обов’язкове поле. Надійно для чіткого тригера («відкрий кошик, коли відвідувач каже, що хоче оформити замовлення»).

Прив’язана до інструмента — детерміновано. Задайте emits_event на власному інструменті, і рантайм сам надсилає подію на кожен непорожній результат, а не коли моделі заманеться:

подія з полем array отримує в це поле весь список результату (обрізаний за response_path інструмента), а скалярні поля — з першого елемента;
подія лише зі скалярними полями надсилається рівно для одного елемента результату, зіставленого за назвою;
поле без required тут вважається обов’язковим, тож на необов’язкових полях явно вказуйте required: false.

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

Пріоритет

Один хід тримає одну пропозицію. Коли кілька результатів конкурують: притриманий план дій на сторінці важливіший за тизер події, який важливіший за перенаправлення на сторінку. З confirm притримана подія чекає на «так» відвідувача; з teaser відповідь — один рядок, а інтерфейс хоста і є відповіддю.

Як малювати добре

Малюйте там, куди дивиться відвідувач — у сітці товарів, а не в бульбашці чату — і тримайте власну відповідь віджета короткою через teaser.
Тримайте слухача на кожній сторінці, де подія може спрацювати: подія надсилається незалежно від того, чи хтось її слухає, а показує результат саме та сторінка, що слухає.
Віджет у кутку; модальне вікно, що його накриває, — нормально: віджет відступає для дій на сторінці, а не для вашого інтерфейсу.

Приклад з життя

Власне демо магазину на маркетинговому сайті: інструмент catalogue_search, прив’язаний до події show_products з одним полем array. «Червона сукня на весілля, до 2 000» викликає інструмент, рантайм надсилає подію зі збігами, а слухач сайту малює панель товарів у власному стилі сторінки. Його сусід на тому ж сайті, subscription_search, прив’язаний до subscription_lookup, читає справжню сітку тарифів і малює ті тарифи, що підходять під питання. Обидва зібрано крок за кроком, разом з ендпоінтом, у покроковому прикладі.