Виджет во встроенной странице

Свяжите действия виджета со встроенной страницей приложения, чтобы помощник мог находить нужные элементы.

Основной раздел: Public API и события.

Действия во встроенном приложении

Обычным страницам достаточно разметки элементов. Для отдельного приложения со своим протоколом управления можно передать pageElementActions в init. Это локальный адаптер сайта, не инструмент MCP; через updateRuntime он не меняется.

• execute(payload) получает event_id, attempt_id, action, target либо target_chain и, для ввода или выбора, value. Цель содержит context_id, необязательную role и пару entity_type/entity_id для конкретной сущности.
• Верните null, если цель не относится к приложению: её обработает загрузчик. Для своей цели верните результат с теми же event_id, attempt_id, action, временем executed_at и статусом success, not_found, blocked или failed. Для отказа добавьте error_code и понятный error_message.
• execute поддерживает Promise и должен завершиться за 2,5 секунды. После исключения, неверного результата или тайм-аута загрузчик сообщает ошибку и не повторяет действие другим способом. Не отбрасывайте ограничения цели: если приложение не умеет выбирать конкретную сущность, верните blocked.
• clear(scope) очищает подсветку адаптера: tool относится к подсказке агента, selected к выбранному пользователем элементу, all к обеим. Загрузчик вызывает очистку при новой команде, закрытии подсказки и уничтожении экземпляра.

SenlerWidget.init({
  channel_id: "YOUR_CHANNEL_ID",
  pageElementActions: {
    async execute(payload) {
      const target = payload.target ?? payload.target_chain.at(-1);
      if (!target?.context_id.startsWith("my-app.")) return null;
      return appBridge.execute(payload);
    },
    clear(scope) {
      appBridge.clearHighlights(scope);
    },
  },
});

appBridge реализует разработчик приложения; это не метод Senler. Его execute должен сохранить полную цель и вернуть результат описанного выше формата. Не подключайте рядом второй слушатель PAGE_ELEMENT_ACTION: загрузчик уже принимает команду и отправляет результат.

При передаче команды дочерним iframe загрузчик ждёт ответ одного окна, прежде чем обращаться к следующему. Продолжить поиск позволяет только not_found; успех, отказ или ошибка завершают попытку. На поиск в дочерних окнах отводится 2,5 секунды. Если к этому моменту текущий iframe не ответил, возвращается failed с кодом child_frame_action_timeout, без повторного выполнения в другом окне. Тайм-аут не доказывает, что действие не произошло: перед повтором проверьте состояние приложения.

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

Необязательный обработчик pageElementActions.navigate(payload, { element, signal, execute }) позволяет подготовить интерфейс сайта перед действием «Показать на странице»: например, свернуть панель, которая закрывает нужный элемент. Он вызывается только для highlight и scroll_to с user_initiated: true, а не для автоматических команд агента, нажатий или заполнения полей.

element содержит найденный до подготовки элемент либо null. После изменения интерфейса вызовите execute() и верните его результат: загрузчик заново найдёт цель с учётом новой разметки. Повторные вызовы этой функции в рамках одной попытки возвращают тот же Promise и не дублируют действие. Используйте signal, чтобы прекращать подготовку при отмене запроса; не выполняйте подсветку самостоятельно по сохранённому element.