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

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

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

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

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

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

Размечайте основную страницу сайта, а не элементы внутри iframe самого виджета. Внутренние маркеры чата используются интерфейсом Senler и не являются целями подсветки или действий на странице сайта.

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

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

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

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

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

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

Определите выбираемые элементы

Выбираемыми считаются:

элементы с data-ai-context-id, data-ai-label, data-ai-kind, data-ai-action, data-ai-kb-doc-id, data-ai-kb-query, data-ai-reveals-context-id или data-ai-reveal-action;
стандартные элементы button, a, input, textarea, select, label, summary;
текстовые и структурные элементы article, section, li, p, h1-h6;
элементы с ролями button, link, menuitem, tab, checkbox, combobox, radio, option, searchbox, textbox;
элементы с aria-label или aria-labelledby.

data-ai-section сам по себе только описывает секцию. Если нужно выбрать весь блок, добавьте на него data-ai-label, data-ai-kind или data-ai-context-id.

Название выбранного элемента определяется по первому подходящему источнику: data-ai-label, aria-labelledby, связанный или ближайший label, aria-label, title, placeholder, затем видимый текст. Поэтому сначала исправляйте обычную HTML/ARIA-подпись, а data-ai-label используйте, когда интерфейсное название недостаточно понятно вне страницы.

Для повторяющихся строк и карточек всегда задавайте data-ai-entity-type и data-ai-entity-id парой. Общий data-ai-context-id описывает вид элемента, например строку лида, а пара сущности указывает на конкретного лида. Атрибуты читаются с самого выбранного элемента и не наследуются от родителя: если внутри повторяющейся карточки есть отдельная выбираемая кнопка, повторите пару сущности и на ней. Если на экране несколько элементов с одним контекстным ключом, действие без этой пары считается неоднозначным и не выполняется. Передача только одного из двух атрибутов также недопустима.

Добавьте нужные атрибуты

Все значения — строки. Ограничения в таблице соответствуют объёму данных, который виджет сохраняет в контексте выбранного элемента.

Атрибут	Для чего нужен	Ограничение / пример
`data-ai-area`	Стабильное имя крупной области страницы.	До 80 символов; например `header`, `navigation`, `content`, `form`, `modal`.
`data-ai-section`	Смысловой раздел внутри страницы.	До 120 символов; например `catalog`, `checkout-payment`, `profile-settings`.
`data-ai-label`	Понятное человеку название элемента вне контекста страницы.	До 180 символов.
`data-ai-kind`	Тип элемента в терминах продукта.	До 80 символов; например `primary-action`, `form-field`, `product-card`.
`data-ai-action`	Смысл действия элемента.	До 120 символов; например `cart.add` или `checkout.pay`. Не выдаёт разрешение на выполнение.
`data-ai-context-id`	Стабильная связь с документацией и точная цель действия.	До 120 символов; рекомендуется lowercase-ключ через точки, например `checkout.payment.submit`.
`data-ai-kb-doc-id`	Прямая ссылка на известный стабильный ID документа базы знаний.	До 80 символов. Не используйте как основную связь для переимпортируемой MD-документации.
`data-ai-kb-query`	Запасная поисковая фраза для базы знаний.	До 240 символов; например `как оплатить заказ`.
`data-ai-entity-type`	Тип конкретной сущности в повторяющемся списке.	До 80 символов; например `product`, `plan`, `order`.
`data-ai-entity-id`	ID конкретной сущности.	До 120 символов; например SKU или публичный ID тарифа. Всегда используйте вместе с `data-ai-entity-type`.
`data-ai-reveals-context-id`	Контекстный ключ или корень ключей, которые показывает этот переключатель.	Один или несколько ключей через пробел; до 2 000 символов суммарно.
`data-ai-reveal-action`	Способ раскрыть скрытую цель.	`click`, `hover` или `focus`; без атрибута используется `click`.
`data-ai-value`	Текущее значение нестандартного списка или значение его варианта для действия выбора.	Например `off`. Не помещайте сюда секреты; это значение для управления списком, а не его подпись.

Для действий на основной странице виджет сравнивает data-ai-context-id, data-ai-entity-type и data-ai-entity-id с учётом регистра и знаков: Catalog.save и catalog.save, item-a и item_a — разные ключи. Передавайте их в команды и документацию без изменений. Значения data-ai-reveals-context-id должны совпадать с ключом цели или его корнем: catalog раскрывает catalog.save, но не catalogue.save и не Catalog.save.

data-ai-action описывает назначение элемента, но не заменяет авторизацию, проверку прав и подтверждение на стороне сайта. data-ai-reveals-context-id и data-ai-reveal-action нужны только для нестандартных меню и панелей; стандартные связи aria-controls, popovertarget, commandfor и <details>/<summary> виджет определяет сам.

Чтобы data-ai-context-id извлекался из Markdown при загрузке в базу знаний, используйте не более 120 символов и как минимум две непустые части через точку. В частях допустимы латинские буквы, цифры, _ и -. Например, checkout.payment.submit подходит, а payment, checkout..submit и ключ с пробелом — нет.

Не помещайте в атрибуты пароли, токены, email, телефон, персональные данные или секретные служебные ID. Значения атрибутов и видимый текст выбранного элемента передаются агенту вместе с вопросом.

Нестандартные списки выбора

Обычный HTML select работает без дополнительной разметки вариантов. Для списка из кнопки и всплывающей панели поставьте data-ai-context-id на кнопку, задайте ей role="combobox", aria-expanded, aria-controls с ID панели и data-ai-value с текущим значением. Клавиша ArrowDown должна открывать панель с role="listbox". Вариантам нужны role="option", data-ai-value и aria-selected; для недоступного варианта используйте aria-disabled="true".

После выбора обновите значение кнопки или aria-selected варианта. Виджет проверяет это изменение, прежде чем сообщить об успехе. Значение ищется сначала по value/data-ai-value, затем по подписи; при одинаковых подписях нескольких вариантов выбор не выполняется. Если рядом с названием есть длинное пояснение, укажите короткое название отдельно в data-ai-label варианта.

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

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

С каких сценариев начать

Интернет-магазин: пользователь спрашивает "как оплатить заказ?", находится статья про оплату и показывается кнопка с data-ai-context-id="checkout.payment.submit".
SaaS-форма: пользователь не понимает, куда вставить токен, а data-ai-context-id поля из документации помогает подсветить нужное поле ввода.
Личный кабинет: пользователь спрашивает про настройку уведомлений, сначала показывается пункт меню на текущей странице, а затем объясняется, что делать после перехода.

Во всех сценариях текст статьи остается человеческим: "нажмите кнопку оплаты", "введите токен", "откройте уведомления". Контекстный ключ находится в атрибуте span и не мешает читать инструкцию.

Пример: карточка товара

<main data-ai-area="content" data-ai-section="catalog">
  <article
    data-ai-label="Товар: Кроссовки Alpha"
    data-ai-kind="product-card"
    data-ai-context-id="catalog.product-card"
    data-ai-kb-query="как выбрать товар и размер"
    data-ai-entity-type="product"
    data-ai-entity-id="sku-alpha-42"
  >
    <h2>Кроссовки Alpha</h2>
    <p>Размеры 39-44</p>
    <button
      data-ai-label="Добавить Кроссовки Alpha в корзину"
      data-ai-kind="primary-action"
      data-ai-action="cart.add"
      data-ai-context-id="cart.add"
      data-ai-kb-query="как добавить товар в корзину"
      data-ai-entity-type="product"
      data-ai-entity-id="sku-alpha-42"
    >
      В корзину
    </button>
  </article>
</main>

Пример: тарифы и оплата

<section data-ai-area="content" data-ai-section="pricing">
  <div
    data-ai-label="Тариф Pro"
    data-ai-kind="plan-card"
    data-ai-context-id="pricing.plan.pro"
    data-ai-kb-query="чем отличается тариф Pro"
    data-ai-entity-type="plan"
    data-ai-entity-id="pro"
  >
    <h3>Pro</h3>
    <button
      data-ai-label="Выбрать тариф Pro"
      data-ai-kind="primary-action"
      data-ai-action="plan.choose"
      data-ai-context-id="pricing.plan.choose"
      data-ai-kb-query="как выбрать и оплатить тариф"
      data-ai-entity-type="plan"
      data-ai-entity-id="pro"
    >
      Выбрать
    </button>
  </div>
</section>

Пример: форма

<form data-ai-area="form" data-ai-section="checkout-delivery">
  <label for="delivery-city">Город доставки</label>
  <input
    id="delivery-city"
    name="city"
    data-ai-label="Город доставки"
    data-ai-kind="form-field"
    data-ai-context-id="checkout.delivery.city"
    data-ai-kb-query="как указать город доставки"
  />
  <button
    data-ai-label="Продолжить оформление заказа"
    data-ai-kind="primary-action"
    data-ai-action="checkout.continue"
    data-ai-context-id="checkout.continue"
    data-ai-kb-query="как продолжить оформление заказа"
  >
    Продолжить
  </button>
</form>

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

Если на сайте есть 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 с естественной фразой;
проверьте, что документ активен и подключен к нужному агенту;
убедитесь, что вопрос отправлен с выбранной плашкой элемента в виджете.