Админка

Откройте Компоненты → BannerPro (manager/?a=index&namespace=bannerpro). Контроллер BannerProIndexManagerController монтирует Vue 3-приложение в #bannerpro-mgr-app и передаёт конфиг в window.bannerproConfig.

Нужен VueTools. Без него страница покажет предупреждение и не загрузит PrimeVue-компоненты.

Вкладки зависят от прав ACL:

Вкладка	Когда видна
Баннеры	Есть bannerpro_save или bannerpro_remove (не режим «только статистика»)
Позиции	То же
Статистика	Есть bannerpro_stats
Журнал	Есть bannerpro_save
Настройки	Есть bannerpro_save

Контент прокручивается в области #modx-content менеджера MODX. Таблицы PrimeVue не создают отдельный вертикальный скролл.

Права доступа

Permission	Что разрешает
view	Открывает компонент в менеджере
bannerpro_save	Создаёт и редактирует баннеры, позиции, связи, порядок, вес, журнал, вкладку «Настройки»
bannerpro_remove	Удаляет баннеры и позиции
bannerpro_stats	Статистика, графики, экспорт CSV, сводка за 7 дней

Без bannerpro_save кнопки создания и редактирования скрыты. Connector вернёт HTTP 403 при прямой попытке изменить данные.

Режим «только статистика»

Если у пользователя есть bannerpro_stats, но нет bannerpro_save и bannerpro_remove, открывается только вкладка Статистика. Вкладки «Баннеры» и «Позиции» скрыты.

save	remove	stats	UI
1	*	*	Полный доступ
0	0	1	Только «Статистика»

Сводка «Последние 7 дней»

Над списком баннеров (при bannerpro_stats) виджет показывает KPI за последние 7 дней:

Метрика	Смысл
Клики	Уникальные клики (IP + баннер + позиция, раз в сутки)
Показы	Уникальные показы при включённом учёте
CTR	Клики / показы
Заказы	Конверсии MiniShop3 с атрибуцией BannerPro
CVR	Заказы / клики

Кнопка Подробнее переключает на вкладку «Статистика».

Чеклист первой настройки

На вкладке Баннеры (пока шаги не выполнены и панель не скрыта) отображается блок «Настройка BannerPro».

Пункт	Условие «готово»	Куда ведёт кнопка
Позиции	Есть хотя бы одна позиция	Вкладка «Позиции»
Баннеры	Есть хотя бы один баннер	Вкладка «Баннеры»
Привязки	Есть хотя бы одна связь баннер↔позиция	Вкладка «Баннеры»
Clickout	Плагин BannerProClickout включён	Без кнопки
Показы	Опциональное предупреждение, если bannerpro_track_impressions = Нет	Вкладка «Настройки»

После выполнения обязательных пунктов панель можно скрыть. Состояние хранится в localStorage (bannerpro_setup_dismissed=1).

Панель видна, пока хотя бы один пункт не в статусе «готово». Пункт Clickout не имеет кнопки перехода: включите плагин BannerProClickout в Элементы → Плагины. Пункт Показы появляется только при bannerpro_track_impressions = Нет. На скриншотах ниже панель уже скрыта после настройки демо-стенда.

Вкладка «Баннеры»

Список

• Серверная пагинация: 10 / 20 / 50 / 100 строк
• Сортировка по колонкам
• Поиск по названию и описанию
• Подсказка: двойной клик по строке открывает редактирование
• Empty state: «Баннеров пока нет» с кнопкой создания (при bannerpro_save)

Колонки строки:

Элемент	Содержимое
Чекбокс	Выбор для массовых действий
Баннер	Миниатюра или тип HTML, название, ID, URL (id) pagetitle, категория MS3
Клики · заказы	Счётчики кликов и конверсий MS3
Расписание	Краткий статус периода / часов
Действия	Редактировать, дублировать, вкл/выкл, удалить

Неактивные баннеры визуально приглушены.

Фильтры

Базовые:

Фильтр	Значения
Активен	Все / Да / Нет
Тип	Все / Изображение / HTML
Позиция	Все или одна позиция
Поиск	Название и описание

Расширенные (аккордеон):

Фильтр	Значения
Товар	Все / без товара (глобальные) / конкретный товар (autocomplete)
Категория MS3	Autocomplete категории
Метка	Suggest по существующим тегам

Кнопка сброса очищает все фильтры. Фильтр on_schedule (показ по расписанию «сейчас») есть в connector, в UI не выведен.

Панель действий

Действие	Описание
Новый баннер	SplitButton: основная кнопка создаёт пустой баннер
Создать из шаблона	Пункт меню SplitButton: диалог выбора preset из bannerpro_ad_templates
Обновить	Перезагрузка списка
Редактировать	Иконка карандаша или двойной клик
Дублировать	Копия с теми же позициями, idx и весом. К названию добавляется « (копия)»
Вкл / Выкл	Переключает active без открытия формы
Удалить	ConfirmDialog, затем ads_remove

Без позиций создание, шаблон и редактирование покажут предупреждение: сначала создайте позицию.

Создание из шаблона

SplitButton Новый баннер → Создать из шаблона открывает диалог TemplatePicker:

Элемент	Поведение
Сетка карточек	Preset из таблицы bannerpro_ad_templates: имя, тип (image/html), чанк tpl
Выбор	Клик по карточке. Двойной клик — выбрать и подтвердить
Кнопки	Отмена, Выбрать (активна после выбора карточки)

После подтверждения connector вызывает ads_create_from_template, открывает форму баннера с заполненными полями и пишет запись в журнал (create_from_template). REST: POST /ads/from-template при включённой записи API.

Массовые действия

Выберите строки чекбоксами. Появится панель:

Кнопка	Действие
Включить	ads_bulk_enable
Выключить	ads_bulk_disable
Добавить к позициям	Диалог MultiSelect позиций
Удалить	ConfirmDialog → ads_bulk_remove

Лимит одной bulk-операции: 100 баннеров.

В диалоге назначения позиций:

• MultiSelect: одна или несколько позиций
• Чекбокс «Заменить текущие позиции»: снимает старые связи и ставит выбранные. Без флажка позиции добавляются к существующим

Диалог баннера

Форма разбита на три вкладки. Тип (изображение / HTML) переключается сегментированными кнопками.

Вкладка «Основное»

Поле	Описание
Название	Внутреннее имя баннера
Активен	Toggle показа на сайте
Тип	Изображение или HTML
Изображение	Браузер медиа + превью. Для типа «Изображение»
Источник файлов	Media Source (расширенный блок). По умолчанию из конфига менеджера
HTML	Код баннера. При заполненном URL оборачивается в ссылку клика
Превью HTML	iframe sandbox
URL	Autocomplete ресурса MODX или внешний адрес. Поддерживает плейсхолдеры клика
Описание	Текст для alt / title / своего чанка
Позиции	MultiSelect рекламных позиций

Вкладка «Показ»

Поле	Описание
Начало / Конец	Период показа. Пусто = без ограничения
Пресеты расписания	Рабочие 9–18 (пн–пт, 9–18) и Круглосуточно (сброс дней и часов)
Дни недели	MultiSelect 1–7 (пн–вс)
Часы	MultiSelect 0–23 (show_hours)
Статус «Сейчас»	Показывается / вне расписания (по часам браузера менеджера)
Лимит кликов	max_clicks, 0 = без лимита
Лимит показов	max_impressions, 0 = без лимита

При достижении лимита баннер скрывается на сайте. Флаг active не сбрасывается.

Вкладка «Таргетинг»

Поле	Описание
Страница	Конкретный ресурс (target_resource_id)
Раздел	Дочерние страницы родителя (target_parent_id)
Метки	Chips + suggest. Фильтр сниппета &tags=
Товар MiniShop3	MultiSelect на один товар. Поиск до 200 записей
Подставить URL	Пишет [[~{id}]] в поле URL
Отвязать	Сбрасывает product_id
Категория MiniShop3	Баннер для товаров категории. Взаимоисключимо с товаром

Страница и раздел нельзя задать одновременно: заполнение одного блокирует другое. Товар и категория тоже нельзя сочетать.

Пикер товара не загружает весь каталог. Без фильтра показывает первые 200 опубликованных msProduct. При редактировании привязанный товар остаётся в списке, даже если не попал в текущую выборку.

Что попадает на сайт

Для каждой пары «баннер + позиция» создаётся запись byAdPosition с полем idx (порядок). В шаблоне используйте плейсхолдер adposition: ID этой связи для ссылки клика, не ID баннера.

Вкладка «Позиции»

Позиция задаёт логический слот на сайте: sidebar, header, shop-product-sidebar.

Список

• Пагинация 10 / 20 / 50 / 100
• Колонки: название, ID, контекст (или «все контексты»), клики
• Действия справа: редактировать, дублировать, удалить
• Двойной клик открывает форму
• Empty state при пустом списке

Действие	Что делает
Создать	Имя позиции и опционально context_key
Редактировать	Имя, контекст и список баннеров в позиции
Дублировать	Копия с теми же баннерами, порядком и весом
Удалить	Удаляет позицию и связи с баннерами

Контекст (context_key): ключ MODX (web, mgr, …). Пустое поле: позиция во всех контекстах. На сайте сниппет фильтрует по текущему контексту. Явный override: &context= в сниппете. Подробнее: Интеграция.

Баннеры в позиции

В диалоге редактирования позиции:

Действие	Описание
Добавить баннер	Выбор из списка, исключая уже привязанные
Удалить из позиции	Снимает связь byAdPosition
Порядок	Drag-and-drop строк обновляет idx
Вес	weight ≥ 1 для sortby=weighted на сайте

Имя позиции для сниппета стабильнее ID:

fenom

{'!BannerPro' | snippet : ['positionName' => 'sidebar', 'tpl' => 'byAd']}

modx

[[!BannerPro?
  &positionName=`sidebar`
  &tpl=`byAd`
]]

Альтернатива: числовой параметр &position= (ID из списка).

Вкладка «Статистика»

Доступна при праве bannerpro_stats.

Фильтры и KPI

Элемент	Описание
Период	Всё время, сегодня, последние 7 дней, эта/прошлая неделя, текущий/прошлый месяц, текущий год
Позиция	Все позиции или одна
Сравнить с прошлой неделей	Toggle виден при периоде Эта неделя (или если сравнение уже включено). Два ряда на графике, % delta на KPI, CompareLineChart
Экспорт CSV	Сводка за выбранный период (stats_export, type report)

KPI: клики, показы, CTR, заказы, CVR. Подсказки на карточках объясняют правила учёта.

Блоки ниже фильтров:

Блок	Содержимое
График по дням	Клики, показы, заказы (StatsLineChart или CompareLineChart)
Воронка	Показ → клик → заказ (+ CTR / CVR)

Вкладки статистики

Вкладка	Содержимое
Обзор	Топ баннеров: клики, показы, заказы, CTR. Серверная пагинация 10 / 20 / 50
Клики	Столбчатый график по баннерам
Рефереры	Таблица referrer + клики с учётом фильтра позиции. Empty state при пустых данных

Правила учёта

Клики: один с IP в сутки на пару баннер + позиция. URL /{bannerpro_click}/{adposition}.

Показы: только при bannerpro_track_impressions. Один показ с IP в сутки. Фиксация через IntersectionObserver (порог 50% видимости) и pixel /{bannerpro_impression}/{adposition}.

Очистка статистики: connector action stats_purge (право bannerpro_remove) и cron core/components/bannerpro/cron/purge.php по настройкам retention. Кнопки в UI нет.

Вкладка «Журнал»

Доступна при bannerpro_save.

Элемент	Описание
Фильтр объекта	Баннер (ad) / позиция (position)
Фильтр действия	См. таблицу ниже
Колонка «Событие»	Действие + тип объекта + подпись
Колонка «Когда»	Дата и пользователь
Payload	Кнопка Детали открывает Popover с JSON diff (поля до/после, bulk-метаданные)
Empty state	«Записей в журнале нет» при пустой выборке или до первых изменений

Действия в фильтре:

Action	Когда пишется
create	Создание баннера или позиции
update	Редактирование
delete	Удаление
enable / disable	Вкл/выкл баннера
bulk_enable / bulk_disable / bulk_delete	Массовые операции
bulk_assign_positions	Массовое назначение позиций
create_from_template	Создание из шаблона

Пагинация и сортировка серверные.

Вкладка «Настройки»

Доступна при bannerpro_save. Редактирует часть ключей без перехода в Система → Настройки системы.

Блок UTM

Connector: settings_utm_get / settings_utm_update.

Поле в UI	Ключ MODX
Включить UTM	bannerpro_utm_enabled
utm_source	bannerpro_utm_source
utm_medium	bannerpro_utm_medium
utm_campaign	bannerpro_utm_campaign
utm_content	bannerpro_utm_content

Плейсхолдеры в utm_content: {ad_id}, {adposition}, {product_pagetitle}, {order_id} и другие из настроек.

Блок webhook и A/B

Connector: settings_integrations_get / settings_integrations_update.

Поле в UI	Ключ MODX
URL webhook клика	bannerpro_webhook_url
URL webhook показа	bannerpro_webhook_impression_url
Секрет HMAC	bannerpro_webhook_secret
TTL cookie A/B (дни)	bannerpro_ab_ttl (1–365)

Кнопка Сохранить пишет оба блока одним действием.

Остальные ключи (кэш, аналитика, REST API, retention, боты, lazy-load) — в Система → Настройки системы, namespace bannerpro. Полный список: Системные настройки.

Типичный рабочий процесс

1. Создайте позицию sidebar (при необходимости задайте context_key).
2. Создайте баннер, задайте URL и контент, привяжите к sidebar.
3. В шаблоне вызовите BannerPro с positionName=sidebar.
4. Кликните по баннеру на сайте.
5. Откройте Статистика и проверьте клик.
6. При необходимости включите UTM, webhook или показы во вкладке Настройки / системных настройках.

Чеклист на вкладке «Баннеры» подсветит пропущенные шаги.

Технические детали

Часть	Путь
Контроллер	core/components/bannerpro/controllers/index.class.php
Шаблон менеджера	core/components/bannerpro/templates/default/index.tpl
Connector	assets/components/bannerpro/connector.php
Vue entry	assets/components/bannerpro/js/mgr/src/entry.js
Собранный бандл	assets/components/bannerpro/js/mgr/vue-dist/bannerpro-admin.min.js

Лексиконы админки: ru, en, uk. Язык берётся из manager_language.

Список connector actions: События и connector.

Что дальше

• Быстрый старт: первый баннер на сайте.
• Интеграция: ротация, A/B-деление, таргетинг, клики и показы.
• Системные настройки: полный список ключей bannerpro_*.
• MiniShop3: баннеры на карточке товара и атрибуция заказа.