О документе

Документ подготовлен для Bussol: Видеовиджеты PRO — Bubble, Stories, Carousel, A/B и аналитика, версия 1.1.1, на основе фактической реализации релизного архива и в структуре, близкой к эксплуатационной документации BUSSOL DataBridge. Он предназначен для администратора сайта, маркетолога, интегратора и разработчика.

1. Назначение и модель работы

Модуль BUSSOL: Видеовиджеты PRO организует управляемый показ видеоконтента на сайтах 1С-Битрикс и объединяет в одном решении плавающие видеовиджеты, Stories, Carousel, eCommerce-действия, сегментацию, A/B-тестирование и аналитику. Версия 1.1.1 предназначена для администратора сайта, маркетолога, интегратора и разработчика.

↑ К содержанию

2. Возможности версии 1.1.1

• Пять форматов: Bubble, Popup, Inline, Stories и Carousel; одновременно на странице может работать несколько независимых экземпляров.
• Локальные MP4/WebM/MOV/M4V, прямые MP4/WebM URL, HLS, YouTube, Rutube и VK Видео; отдельные preview, poster и mobile-видео.
• URL include/exclude, wildcard-маски, ограниченные регулярные выражения, расписание, delay, scroll, exit intent, inactivity, pageviews и повторный визит.
• Frequency cap: каждый раз, раз за сессию, раз в сутки, раз в N дней или никогда после закрытия.
• Сегментация по авторизации, группам, устройству, новому/вернувшемуся посетителю, referrer, UTM и состоянию корзины.
• CTA: URL, телефон, WhatsApp, Telegram, CSS-форма/элемент, штатная веб-форма Bitrix, корзина, «Купить сейчас», anchor и JS CustomEvent.
• eCommerce: товар и количество для виджета или отдельной карточки Stories/Carousel; серверное добавление в корзину и безопасный переход к оформлению заказа.
• Встроенная статистика, Яндекс.Метрика, DataLayer/GTM, DOM-события и публичный JavaScript API.
• Стабильное A/B-распределение с весами, периодом теста, основной метрикой и 95% Wilson confidence interval.
• Полная многосайтовость, поддержка Композита и Сайты24 с отдельным Inline-блоком.
• Импорт видео из старого bussol.vwidget, сохранение данных при удалении, автоматическое обновление схемы.
• Security hardening 1.1.1: CSRF/sessid, SSRF-защита webhook, HMAC-подпись, allowlist URL/upload, ReDoS limits и серверная валидация trusted-событий.

↑ К содержанию

3. Системные требования

↑ К содержанию

4. Установка, обновление и удаление

Чистая установка

1. Скопируйте каталог bussol.vwidget2 в /bitrix/modules/ либо установите решение штатным механизмом Marketplace.
2. Откройте «Marketplace → Установленные решения» и установите «Bussol: Видеовиджеты PRO — Bubble, Stories, Carousel, A/B и аналитика».
3. Установщик создаст таблицы модуля, зарегистрирует обработчики AutoRenderer и меню, агент очистки аналитики, компонент, tools-endpoints, тему и при наличии landing — Inline-блок Сайты24.
4. Откройте «Bussol → Bussol: Видеовиджеты PRO → Настройки», проверьте авто-рендер, статистику, Метрику, срок хранения, webhooks, URL заказа и HLS.
5. Перейдите в «Виджеты», создайте неактивный тестовый виджет и проверьте его на целевой странице.

Обновление 1.0.0 / 1.1.0 → 1.1.1

• Сделайте резервную копию каталога модуля и базы данных.
• Используйте штатный механизм обновлений Marketplace или замените файлы модуля без удаления таблиц.
• SchemaService автоматически проверяет схему и добавляет недостающие поля/индексы без удаления существующих виджетов и статистики.
• После обновления проверьте кеш, Композит, один плавающий формат, Inline, аналитику и используемые интеграции.
• Версия 1.1.1 повторно валидирует сохранённые URL/CTA/regex при рендере, поэтому старые небезопасные значения не должны попадать в публичный HTML.

Удаление

Деинсталлятор удаляет обработчики, агент, компонент, tools-endpoints, тему, административные прокси и блок Сайты24. В диалоге удаления можно сохранить таблицы и накопленные данные. Общая иконка раздела Bussol намеренно сохраняется, поскольку её могут использовать другие модули Bussol.

Миграция из bussol.vwidget

1. Установите v2 параллельно со старым модулем.
2. Откройте «Импорт из v1» и выберите сайты.
3. Импорт переносит название и видео из инфоблока bussol_videowidgets и создаёт новые виджеты неактивными.
4. Вручную проверьте позиции, URL-условия и CTA: в v1 эти параметры не хранились в инфоблоке.
5. После теста деактивируйте старые вставки v1 и активируйте v2.

↑ К содержанию

5. Права, настройки и навигация

Права групп

Путь к интерфейсу: «Bussol → Bussol: Видеовиджеты PRO». Внутри доступны «Виджеты», «Статистика», «Импорт из v1» и «Настройки». Несколько модулей Bussol используют общий корневой раздел global_menu_bussol.

Глобальные настройки модуля

↑ К содержанию

6. Создание и параметры видеовиджета

Редактор разделён на семь вкладок: «Основное», «Дизайн», «Показ», «Сегментация», «CTA / eCommerce», «A/B и аналитика», «Stories / Carousel». Это позволяет отделить контент и внешний вид от маркетинговой логики.

Базовые значения нового виджета

↑ К содержанию

7. Форматы и медиаисточники

Источники видео

Для desktop и mobile можно выбирать независимые источники. Локальное mobile-видео может отличаться от desktop. Preview-видео и poster используются для первого контакта и помогают уменьшить ненужную загрузку основного источника.

Поведение проигрывания

• Autoplay, muted и loop задаются на уровне виджета.
• Bubble использует preview до раскрытия; после открытия переключается на основной источник.
• Для локального/direct/HLS-видео рассчитываются video_start, 25%, 50%, 75% и video_complete.
• Для YouTube/Rutube/VK в 1.1.1 доступны show/open/CTA, но квартильные события 25/50/75/100 не вычисляются без отдельного API провайдера.

↑ К содержанию

8. Правила показа, триггеры и частота

URL-правила

Триггеры

Frequency cap

Frequency и стабильное A/B-распределение используют клиентское хранилище браузера. При очистке storage поведение для такого посетителя начнётся заново.

↑ К содержанию

9. Расписание и сегментация аудитории

Расписание

Можно задать дату начала и окончания, разрешённые дни недели и временной интервал. Условия применяются совместно с URL, сайтом, landing-режимом, trigger, frequency и сегментами.

Сегменты

Авторизация, группы и корзина не помещаются в кешируемый HTML: клиент получает их через отдельный no-store endpoint. Если требуемый динамический контекст недоступен, виджет с таким условием не должен показываться.

↑ К содержанию

10. CTA, eCommerce, формы и webhooks

CTA-действия

CTA можно показывать сразу, через N секунд, после N% локального видео либо после окончания. Для Stories/Carousel у каждой карточки может быть собственный label/action/value и собственный товар.

Webhook

Для каждого виджета можно задать публичный HTTPS endpoint и список событий. Разрешённые события: show, open, video_start, video_25, video_50, video_75, video_complete, cta_click, close, cart_add, cart_error, form_open, form_submit. Запрос отправляется JSON POST без редиректов; private/loopback адреса запрещены. Тело до 256 КБ подписывается заголовком X-Bussol-Signature: sha256=<HMAC>.

↑ К содержанию

11. Stories и Carousel

В форматах Stories и Carousel редактор содержит таблицу карточек. Карточки сортируются числовым полем SORT и могут использовать разные источники, CTA и товары в рамках одного виджета.

Если собственный CTA карточки отсутствует, клиент может использовать параметры CTA основного виджета. В viewer фиксируется открытие конкретного item_id, что позволяет анализировать взаимодействие с элементами подборки.

↑ К содержанию

12. Аналитика, Яндекс.Метрика и A/B

События

Страница статистики

• Периоды 7 / 30 / 90 / 180 / 365 дней; фильтры по виджету, устройству и UTM source/medium/campaign.
• KPI: показы, CTA, досмотры, добавления в корзину, формы и проценты от показов.
• Воронка: показ → открытие → 50% видео → досмотр → CTA.
• Таблица событий по каждому виджету с общими и уникальными значениями, CTR и долей досмотра.
• Динамика по дням: показы, открытия, досмотры, CTA, корзина и формы.

A/B-тесты

Виджеты с одинаковой A/B-группой участвуют в стабильном распределении браузера; вес варианта задаётся от 1 до 100. Можно ограничить период теста и выбрать основную метрику: cta_click, cart_add, form_submit, video_complete или open. В статистике конверсия считается по уникальным посетителям и выводится 95% Wilson confidence interval. Модуль не объявляет автоматического «победителя».

Яндекс.Метрика и DataLayer

Метрика использует ID счётчика/префикс виджета либо глобальные значения. DataLayer отправляет события вида bussol_vwidget2_* с widgetId, itemId, productId, A/B-группой, форматом, устройством и UTM.

↑ К содержанию

13. Многосайтовость, Композит и Сайты24

Многосайтовость

• Один виджет может быть привязан сразу к нескольким SITE_ID.
• Связи хранятся в отдельной таблице b_bussol_vwidget2_widget_site; SITE_ID остаётся совместимым основным сайтом.
• Копирование виджета переносит site/landing bindings.
• Список виджетов показывает назначенные сайты и позволяет фильтровать по SITE_ID.

Композит

• Компонент работает в frame mode.
• AutoRenderer не вставляет виджеты в обычные AJAX и composite AJAX-ответы.
• После изменения конфигурации очищаются обычный кеш и Static HTML cache.
• Авторизация, группы, корзина и sessid запрашиваются динамически через no-store endpoint, а не сохраняются в общем HTML-кеше.

Сайты24

Модуль устанавливает отдельный Inline-блок «Bussol: Видеовиджеты PRO … — Inline». В визуальном редакторе Inline-блок может игнорировать публичные URL-правила для удобства настройки, а плавающие форматы не перекрывают интерфейс редактора. На опубликованной странице правила применяются штатно.

↑ К содержанию

14. Расширение разработчиком

Компонент

<?php
$APPLICATION->IncludeComponent(
    'bussol:video.widget2',
    '',
    [
        'AUTO' => 'N',
        'WIDGET_ID' => 12,
        'SITE_ID' => SITE_ID,
        'CACHE_TYPE' => 'N',
    ]
);
?>

JavaScript API

BussolVWidget2.show(12);
BussolVWidget2.hide(12);
BussolVWidget2.open(12);
BussolVWidget2.play(12);
BussolVWidget2.pause(12);
const widget = BussolVWidget2.get(12);
const all = BussolVWidget2.all();

DOM-события

document.addEventListener('bussol:vwidget2:event', (e) => {
    console.log(e.detail.event, e.detail.widgetId, e.detail.itemId);
});

document.addEventListener('myLeadEvent', (e) => {
    console.log(e.detail.widgetId, e.detail.itemId);
});

Каждое событие движка публикуется как bussol:vwidget2:event. CTA типа JS CustomEvent публикует событие с заданным именем. eCommerce также использует bussol:vwidget2:cart и bussol:vwidget2:cart-error.

DataLayer

// Пример структуры события
{
  event: 'bussol_vwidget2_cta_click',
  bussol_vwidget2: {
    widgetId: 12,
    itemId: 0,
    productId: 123,
    abGroup: 'hero-test',
    format: 'bubble',
    device: 'desktop',
    utmSource: 'yandex',
    utmMedium: 'cpc',
    utmCampaign: 'summer'
  }
}

↑ К содержанию

15. Хранение данных и структура модуля

Сырые события очищаются агентом CleanupService::run() один раз в сутки. Период хранения задаётся глобально от 1 до 3650 дней; значение по умолчанию — 180.

↑ К содержанию

16. Безопасность

Версия 1.1.1 прошла pre-submission hardening перед публикацией в Bitrix Marketplace. Финальный security-journal.json привязан к релизному архиву по SHA-256.

↑ К содержанию

17. Ограничения и совместимость

• Поддерживается PHP 8.2+ и main 26.0.0+; обязательный модуль только main. Возможности sale/catalog/form/landing отключаются или gracefully fall back при отсутствии соответствующего модуля.
• Для YouTube/Rutube/VK квартильные события 25/50/75/100 в 1.1.1 не вычисляются без API соответствующего видеопровайдера.
• HLS зависит от поддержки браузера либо от корректно настроенной доверенной сборки hls.js; CSP сайта должна разрешать нужные источники.
• Autoplay со звуком ограничивается политиками браузера; для надёжного preview рекомендуется muted.
• Корзинные действия требуют sale + catalog и должны быть проверены на реальных товарах/SKU используемой редакции.
• Веб-форма требует модуль form и доступ текущего пользователя к форме.
• Сайты24 требуют модуль landing и публичное исполнение страницы тем же ядром Bitrix.
• Архитектурная совместимость с любой редакцией реализована через отсутствие обязательных зависимостей, кроме main, но перед Marketplace требуется интеграционный прогон на конкретных редакциях/лицензиях.
• Статистика использует серверное время и MySQL DATE_SUB/NOW(); убедитесь, что timezone сайта/БД настроены ожидаемо.

↑ К содержанию

18. Диагностика и чек-лист приёмки

Диагностика

Чек-лист приёмки

• Установка на PHP 8.2+ / Bitrix main 26+ проходит без ошибок.
• Базовая редакция без sale/catalog/form/landing показывает Bubble/Popup/Inline/Stories/Carousel без fatal error.
• Редакция интернет-магазина успешно добавляет простой товар и SKU в корзину и выполняет «Купить сейчас».
• Web Form открывается и form_submit фиксируется только после успешной отправки.
• Проверены SITE_ID s1/s2, landing bindings, редактор/preview/публикация Сайты24.
• Композит включён: статический HTML не переносит авторизацию/корзину между пользователями.
• Проверены URL-маски, regex, schedule, все используемые triggers и frequency cap.
• Проверены desktop/mobile размеры, Safari/iOS и Chrome/Android autoplay policies.
• Проверены локальные видео, HLS и реально используемые YouTube/Rutube/VK URL при CSP проекта.
• Яндекс.Метрика, DataLayer/GTM и webhook получают ожидаемые события.
• A/B-варианты распределяются стабильно; в статистике отображаются уникальные показы, конверсии и 95% ДИ.
• Агент очистки зарегистрирован, retention соответствует политике проекта.
• Перед релизом сформирован security-journal.json после последнего изменения кода; SHA-256 журнала совпадает с отправляемым ZIP.

↑ К содержанию