Проактивні знахідки: піднята рука помічника

Для розробників, у коді: інструмент, прив'язаний до екрана, який помічник викликає, коли користувач на ньому затримався, форма знахідок, яку він читає, пауза, і як виміряти, чи піднята рука доречна.

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

Проактивні знахідки входять у тариф Growth і вищі.

У панелі: джерело екрана → Для застосунків → Проактивний аналіз (Джерела).

Як іде запит

Віджет надсилає proactive_tick після того, як користувач пробув на екрані 8 секунд, — лише на екранах, джерело яких називає проактивний інструмент, і лише поки віджет закритий.
Рантайм викликає цей інструмент напряму, без моделі: {{user}} і {{screen.*}} заповнені, аргументів від моделі немає. Порожній результат закінчує запит безкоштовно.
На непорожній результат невеликий хід моделі читає знахідки і або мовчить, або обирає першу варту уваги — спершу про цей екран, гучні перед тихими — і пише одне речення.
Віджет показує речення на бульбашці кнопки запуску з піднятою рукою персонажа. Клік виконує дію знахідки: маршрут для відкриття (через звичайну скасовувану shukai:action:navigate) або питання для надсилання.

Що повертає ваш сервер

JSON-список знахідок або { "findings": [ … ] }. Усе інше вважається порожнім.

[
  {
    "code": "sources_failed",
    "title": "3 сторінки не обробилися",
    "detail": "Обробіть їх знову на екрані «Джерела».",
    "severity": "warning",
    "routes": ["/sites/{siteId}/sources"],
    "action": { "route": "/sites/{siteId}/sources", "params": { "siteId": "c4b7…" } },
    "proactive": true
  }
]

Ключ	Читає код?	Сенс
`code`	так	називає знахідку; тизер несе його, і пауза ключується за ним
`proactive`	так	`false` лишає знахідку для моделі, яка питає, і не включає її в запит — для покращень і виборів, тоді як справжня несправність лишається гучною
`routes`	так	маршрути, які може відкрити клік; розв’язуються відносно поточного екрана, відхиляються, якщо вели б поза origin
`action.route`, `action.params`	так	що робить клік; `params` (скаляри, як рядки) мають пріоритет над параметрами екрана і моделі
`title`, `detail`, `severity`, усе інше	ні	передається моделі як JSON — саме з цього вона пише речення

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

Прив’яжіть до екрана

На джерелі екрана, в розділі Для додатків: Проактивний аналіз — оберіть інструмент — і Повторити через (секунди). Екран без інструмента мовчить; одиниця ввімкнення — екран, а не сайт. Інструмент може бути global або прив’язаний до цього екрана; один інструмент може обслуговувати всі екрани, коли {{screen.route}} каже йому, який питає.

Пауза

Віджет записує, коли яку знахідку показано на якому шляху, і надсилає вік із наступним запитом як shown_ago_ms. Сервер застосовує ваше поточне вікно — секунди джерела, або значення помічника за замовчуванням (24 години), або 0 для кожного входу, — тож скорочення в панелі діє одразу. Закрита знахідка не показується знову в межах вікна; нова знахідка з новим кодом на тому самому екрані — показується.

Виміряйте

Три події несуть detail.codes:

Shukai.on("suggestion:shown", (e) => track("finding_shown", e.detail.codes));
Shukai.on("suggestion:accepted", (e) => track("finding_clicked", e.detail.codes));
Shukai.on("suggestion:dismissed", (e) => track("finding_dismissed", e.detail.codes));

Частка відмов на кожен код — справжній тест. Знахідку, яку люди закривають, не клікаючи, варто зробити тихою ("proactive": false) або перестати повертати.

Вартість і обмеження

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