Разметка элементов сайта

Разметка data-ai-* нужна разработчику сайта, чтобы дать важным элементам устойчивые названия, связать их с инструкциями и сделать точными целями подсветки или разрешённых действий. Начните с одного пользовательского сценария и размечайте только то, что помогает пройти его.

Что меняет разметка

Разметка data-ai-* помогает связать вопрос вида "что это за кнопка?", "как заполнить это поле?", "почему этот тариф недоступен?" с конкретным элементом страницы. Посетитель выбирает элемент на сайте через виджет, а виджет прикладывает к сообщению контекст выбранного элемента.

Разметка отвечает именно за элементы страницы. Контекст текущей страницы, открытой карточки, проекта, заказа или другой бизнес-сущности передается отдельно через Public API виджета: contextProvider, SenlerWidget.setPageContext(items) и одноразовый contextItems для следующего сообщения. По умолчанию этот контекст отображается плашками рядом с сообщением в виджете; элементы с hidden: true остаются скрытыми.

Без разметки виджет тоже использует семантический HTML, подписи форм и ARIA-атрибуты. data-ai-* нужны не вместо доступной вёрстки, а для стабильного ключа, точного названия и связи с базой знаний.

Размечайте элементы своего сайта. Кнопки внутри самого виджета уже размечены: при включённых действиях с элементами сайта агент может показать создание диалога, историю и подключение MCP, если оно доступно в настройках канала. Добавлять для этих кнопок свою разметку или отдельные документы в базу знаний не нужно.

Действия выполняются в интерфейсе виджета или на странице сайта в зависимости от выбранной цели. Не объединяйте их в одну цепочку подсветки. Точные ключи остальных элементов сайта агент получает из контекста или вашей документации.

Подготовьте первый сценарий

Подключите канал «Виджет» и установите полученный код на сайт.
Включите функцию «Выбор элемента» (features.element_selection: true).
Проверьте выбор обычной кнопки или поля с понятной HTML-подписью.
Добавьте data-ai-* к тем элементам, которым нужна стабильная связь с инструкцией или действием.

Если сайт большой, начните с маршрутов, где пользователи чаще всего теряются: регистрация, оплата, подключение, поиск, форма заявки или настройки профиля. Не размечайте декоративные контейнеры и весь DOM «на будущее».

Проверьте путь посетителя

Посетитель нажимает в виджете "Выбрать элемент".
Виджет включает режим выбора на странице.
Посетитель кликает элемент сайта.
Виджет считывает название элемента, раздел страницы, контекстный ключ и поисковую подсказку, если они заданы.
Перед отправкой сообщения пользователь видит выбранный элемент как плашку контекста.
Контекст элемента передаётся агенту вместе с вопросом и помогает найти точную статью.
Если пользователь отдельно просит действие, агент может обратиться к элементу только по точному ключу и только когда страница допускает это действие.

Выбор элемента сам по себе ничего не нажимает и не изменяет: клик посетителя в режиме выбора только создаёт плашку контекста.

Разметьте элементы сценария

Подберите устойчивые ключи и подписи по справочнику атрибутов. Для кнопок, карточек, форм и нестандартных списков используйте примеры разметки. Затем проверьте весь сценарий, а не только отдельную кнопку.

Проверьте качество разметки

Ключ стабилен и не зависит от текста кнопки, языка интерфейса или ID конкретного пользователя.
Видимый текст статьи описывает действие по-человечески, а не повторяет контекстный ключ.
Элемент можно найти в текущей разметке страницы без перехода на другую страницу.
Для кнопки или поля есть label, role или понятный data-ai-label.
У каждой повторяющейся карточки есть одинаковый смысловой data-ai-context-id и своя полная пара data-ai-entity-type / data-ai-entity-id.
Для опасных действий вроде удаления или оплаты в документации сайта отдельно описаны последствия, ограничения и подтверждение.

Связь с базой знаний

Если на сайте есть data-ai-context-id="checkout.delivery.city", добавьте такой же ключ в текст файла базы знаний:

<span data-ai-context-id="checkout.delivery.city">Укажите город доставки</span>.

Когда пользователь выберет поле и задаст вопрос, Senler AI использует context_id для поиска по базе знаний. Документы с совпадающими контекстными ключами получают сильный приоритет.

Если точного ключа нет, помогает data-ai-kb-query: он добавляется к поисковому запросу вместе с названием, видимым текстом и разделом элемента.

Если документация загружается папкой Markdown или ZIP-архивом, не полагайтесь только на видимый текст без разметки. При загрузке inline data-ai-context-id сохраняются как «Контекстные ключи для элементов». Формат файлов и обработка ключей описаны в инструкции «Связь Markdown-документации с элементами сайта».

Что делать после разметки

Сначала свяжите ключи с Markdown-документацией, затем проверьте выбор элемента и каждое разрешённое действие. data-ai-label и data-ai-kb-query помогают объяснению и поиску, но для точного действия нужен data-ai-context-id. Если элемента нет на текущей странице, действие не должно выбирать похожую цель по тексту.

Диагностика

Если элемент не выбирается:

проверьте, включена ли функция "Выбор элемента" в настройках виджета;
проверьте, что пользователь нажал "Выбрать элемент" в виджете;
добавьте на элемент data-ai-label или data-ai-context-id;
не размечайте только родительский контейнер через data-ai-section, если нужно выбрать сам контейнер.

Если нужная инструкция не найдена:

проверьте, что data-ai-context-id совпадает с контекстным ключом файла базы знаний;
добавьте data-ai-kb-query с естественной фразой;
проверьте, что документ активен и подключен к нужному агенту;
убедитесь, что вопрос отправлен с выбранной плашкой элемента в виджете.