Екрани застосунку: навігація й фільтри

Додаток — це набір екранів, і помічник може відкрити лише той, який знає. Екран — це джерело в панелі типу «Екран додатка» з назвою, описом, для чого екран, і одним чи кількома шаблонами маршрутів. Усе інше в роботі з додатком випливає з цього.

Оголошення екрана

У панелі: Джерела → Додати джерело → Екран додатка. Назва, опис, маршрути. Маршрут — це шаблон шляху або повний URL, щоб прив’язати його до одного хоста сімейства сайтів:

/orders
/orders/{id}
https://app.example.com/settings/{siteId}/widgets

Опис — це те, що помічник читає, щоб відповісти «для чого цей екран?» і вирішити, де «мої рахунки». Пишіть так, як пояснювали б екран новому колезі: що на ньому є, що роблять кнопки, по що користувач сюди зазвичай приходить. Це також місце для інструкцій у дусі data-sa-hint про екран загалом.

На якому екрані відвідувач, визначається з URL на кожному повідомленні; додаток з хеш-маршрутизацією оголошує це через Shukai.setContext (Односторінкові додатки).

Навігація за маршрутом

Помічник, який бачить хоч одне джерело-екран, отримує інструмент navigate, призначення якого — рівно оголошені маршрути; вигадати він не може. «Відкрий рахунки за березень» відкриває /orders з виставленим фільтром, якщо екран його оголошує. Плейсхолдер у маршруті ({id}, {siteId}) заповнюється з поточної адреси, з пошуку сутності, який помічник зробив, або з підказки, що підняла руку. Перемагає найконкретніший повністю розв’язаний маршрут: джерело з /widgets і /widgets/{widgetId} відкриває список, доки id невідомий.

Навігація за маршрутом — не дія на сторінці й не обмежується тарифом: помічник на Starter, який бачить екрани, їх відкриває. Що він робить на екрані — заповнює, натискає — це дії на сторінці, від Growth.

URL-фільтри

Екран, який фільтрує сам себе параметрами запиту — ?country=UA, ?status=open, — оголошує ці параметри на джерелі (url_filters), кожен за бажанням із фіксованим списком значень. Тоді помічник фільтрує екран, змінюючи URL, а не керуючи випадним списком, зберігає наявний вибір, додаючи фільтр, і відхиляє значення поза оголошеним списком. «Покажи лише Україну» на екрані аналітики — одна зміна URL, а не послідовність кліків. Оголошуйте фільтр лише там, де набір значень малий і відомий (код країни, перелік); вільнотекстові фільтри краще лишити власним елементам екрана.

Піднята рука на екрані

Екран може назвати проактивний інструмент — HTTP-виклик, який помічник робить після восьми секунд перебування користувача на екрані, без участі моделі. Якщо той повертає знахідки, помічник піднімає руку в кутку з одним реченням про першу, варту уваги; якщо нічого — нічого не відбувається і нічого не витрачається. Пауза — скільки часу та сама знахідка не пропонується знову на цьому екрані — задається на екран і успадковує значення помічника. Проактивні знахідки.

Що помічник бачить на початку ходу

Щойно розмова один раз подивилася на екран, помічник на початку кожного наступного ходу отримує живий маніфест із приміткою, що все раніше в розмові застаріло. Те саме відбувається на ході після навігації, тож місце призначення прочитане до того, як помічник діє. Саме тому розмова в додатку не сканує заново на кожне питання і «екран змінився» ніколи не є для нього несподіванкою.

Користувач за екраном

У додатку помічник діє за користувача, що увійшов, і те, що він може читати з вашого API, — дані цього користувача. Передайте йому власний токен користувача через Shukai.setUser(token) після входу; власний інструмент з Authorization: Bearer {{user}} тоді викликає ваш API від імені цього користувача. Ідентичність користувача.

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

Наша власна панель — додаток, що працює саме так: кожен екран — джерело з маршрутами й описом, кнопки «Зберегти» позначені data-sa-commit, список FAQ-чіпів — оголошений список з віссю мови, кнопка вибору періоду несе aria-expanded, а ко-пілот у кутку панелі редагує вкладку «Контент» віджета трьома мовами за один виклик. Зареєструйтеся й попросіть його змінити колір вашого віджета.