Ads-Flow Docs

Администрирование Ads-Flow

Управление пользователями, компаниями, рекламными тегами, конфигами, iframe-интеграциями и статистикой Ads-Flow.

1. Назначение системы

Ads-Flow — платформа управления рекламным плеером для VAST/VPAID-интеграций. Текущая основная публичная интеграция — автономный out-stream плеер, который подключается на странице площадки через готовый HTML-тег <iframe>.

Администратор создаёт пользователей, компании и общие рекламные теги. Менеджер создаёт конфиги в рамках доступной компании, выбирает разрешённые теги и получает готовый iframe-код. Runtime запрашивает теги по порядку, собирает показатели и сохраняет диагностические события.

Прямой переход по URL вида https://player.ads-flow.net/outstream/pub_xxxxx/ не является полноценной интеграцией. Этот URL предназначен для атрибута src iframe на странице площадки, где плеер может получить referrer и реальное окружение показа.

2. Роли и доступы

  • Admin — видит всех пользователей, все компании, все теги, все конфиги и всю доступную статистику. Может создавать и редактировать Campaigns и Tags, назначать ответственного manager-а и включать/выключать сущности.
  • Manager — работает только с компаниями, в которых он указан. Создаёт и редактирует собственные конфиги, выбирает только теги выбранной компании и видит статистику своих конфигов.
  • Publisher page — внешняя страница, на которой размещён сгенерированный iframe. Публичная сторона не получает VAST URL напрямую: интеграция использует public key конфига.
Manager, входящий в несколько компаний, сначала выбирает Campaign. После выбора доступные managers и Tags ограничиваются этой компанией. Manager не получает доступ к чужим конфигам только из-за общего участия в одной Campaign.

3. Связи Campaign → Tag → Config

Основная иерархия нужна для разделения доступа, повторного использования тегов и корректной статистики.

  • Campaign объединяет managers, доступные рекламные теги и конфиги одной компании или рабочего направления.
  • AdTag хранит имя, описание и шаблон VAST URL. Один тег может быть разрешён нескольким Campaigns.
  • PlayerConfig принадлежит ровно одной Campaign и имеет одного ответственного owner-а.
  • PlayerConfigTag — стабильная связь конфига с тегом. Она хранит порядок тега в очереди. Перетаскивание меняет только порядок, но не идентификатор связи, поэтому статистика остаётся привязана к тому же тегу.
Один и тот же Tag нельзя добавить в один Config дважды. При смене Campaign выбранный набор тегов сбрасывается, чтобы в конфиге не остались теги от другой компании.

4. Users

Раздел Users доступен администратору и используется для создания учётных записей Admin и Manager.

  • Username / Name / Email — данные пользователя.
  • Role — роль Admin или Manager.
  • Active — возможность входа и работы в интерфейсе.
  • После создания Manager его необходимо добавить хотя бы в одну Campaign, иначе он не сможет создать конфиг с доступными тегами.

5. Campaigns

Campaign представляет компанию, команду или отдельное направление работы. Раздел поддерживает фильтры All, Active и Disabled; по умолчанию открывается Active.

  • Name — уникальное название компании.
  • Description — внутреннее описание.
  • Managers / admins — множественный выбор пользователей, которые относятся к Campaign.
  • Active — разрешает публичную работу конфигов Campaign. При отключении Campaign её public iframe-конфиги перестают обслуживаться, но индивидуальные статусы конфигов не перезаписываются.
  • Statistics — общая статистика Campaign с вкладками General, Configs и Tags.
Повторное включение Campaign возвращает в работу только те конфиги, которые сами остались активными.

6. Tags

Раздел Tags доступен администратору. Тег создаётся один раз и затем может использоваться в нескольких конфигах и компаниях.

  • Name — понятное название источника рекламы.
  • Campaigns — компании, которым разрешено использовать тег.
  • VAST URL template — HTTPS URL рекламного тега. Поддерживается runtime-макрос {referrer}.
  • Description — внутренние комментарии.
  • Active — выключенный тег исключается из очередей всех конфигов, даже если связь с конфигом сохранена.
https://ad.example.com/vast?domain={referrer}

Тег без макроса также поддерживается. В этом случае URL запрашивается как сохранён, а referrer всё равно передаётся в статистический контекст Ads-Flow.

7. Player Configs

Player Config — отдельная публичная интеграция. Рекомендуемая модель: один Config для одного publisher-а или одной конкретной площадки, чтобы настройки, public key и статистика не смешивались.

  • Name — внутреннее имя конфига.
  • Campaign — компания, которой принадлежит конфиг.
  • Manager — ответственный owner. Admin выбирает его из managers выбранной Campaign; для Manager текущий пользователь назначается автоматически.
  • Description — назначение интеграции или площадка.
  • Tags — упорядоченная очередь активных тегов. Строки можно перетаскивать. Один Tag выбирается только один раз.
  • Public key — внешний ключ вида pub_xxxxx. Генерируется автоматически и не раскрывает внутренний numeric ID.
  • Width / Height — размеры и пропорции генерируемого iframe.
  • Active — включает public runtime этого конфига.
  • Autoplay — разрешает автоматический старт после достижения требуемой видимости iframe.
  • Muted — начальная громкость 0. Для autoplay наиболее совместимый вариант — Autoplay ON и Muted ON.
Autoplay и Muted читаются runtime-ом из Config при каждой загрузке. После изменения этих параметров повторно копировать iframe необязательно. Width и Height записываются непосредственно в HTML, поэтому после их изменения iframe-код нужно скопировать заново.

8. Публичный iframe

В списке Player Configs кнопка Iframe копирует готовый однострочный HTML. Его нужно вставить в рекламное место на странице publisher-а.

<iframe src="https://player.ads-flow.net/outstream/pub_xxxxx/" title="Ads-Flow out-stream advertisement" width="640" height="360" allow="autoplay; fullscreen" referrerpolicy="strict-origin-when-cross-origin" scrolling="no" frameborder="0" style="display:block;width:100%;max-width:640px;height:auto;aspect-ratio:640/360;border:0;overflow:hidden;background:transparent;position:relative;z-index:2147483647;pointer-events:auto;"></iframe>
  • src содержит public key и загружает автономный runtime.
  • allow="autoplay; fullscreen" разрешает необходимые возможности вложенной странице.
  • width / height задают intrinsic-размер.
  • width:100% позволяет уменьшать iframe до ширины родительского контейнера.
  • max-width ограничивает рост значением Width из Config.
  • aspect-ratio сохраняет пропорции Width / Height.
Ads-Flow управляет рекламой внутри iframe. Размер, положение, резервирование места и схлопывание внешнего рекламного slot контролирует publisher или его рекламная система.

9. Последовательность тегов и внутренние ad pods

При нескольких тегах runtime последовательно проходит все активные Tags конфига в сохранённом порядке. Это не классический waterfall, который останавливается после первого fill.

  1. Плеер отправляет отдельный AdsRequest для первого Tag.
  2. Если Tag возвращает no-fill или ошибку, плеер переходит к следующему.
  3. Если Tag возвращает рекламу, все Ads из внутреннего pod этого Tag воспроизводятся полностью.
  4. После завершения успешного Tag плеер всё равно переходит к следующему Tag конфига.
  5. Общая playback session заканчивается только после обработки последнего Tag.

События tag_request, tag_filled, tag_completed и tag_failed позволяют видеть результат каждой позиции.

10. Referrer и макрос {referrer}

В Ads-Flow referrer означает домен страницы размещения. Значение нормализуется до hostname без схемы, пути, query string и порта: https://news.example.com/article/1 → news.example.com.

  • Основной источник — document.referrer внутри iframe.
  • Дополнительный источник — HTTP Referer первоначального запроса iframe.
  • Для диагностики возможно явно передать ?referrer=publisher.example.
  • Backend подставляет значение только при формировании конкретного VAST Wrapper; шаблон в БД не изменяется.
  • Если Tag содержит {referrer}, но домен получить не удалось, рекламный запрос для этого URL не выполняется.
Политика Referrer-Policy: no-referrer на стороне publisher-а может скрыть значение. Для штатной работы макроса площадка должна разрешать передачу хотя бы origin.

11. Разделы статистики

  • Config Statistics → General — несколько показателей одного конфига на одном графике и в таблице.
  • Config Statistics → Tags — один выбранный показатель с разбивкой по тегам конфига.
  • Campaign Statistics → General — общие итоги доступных конфигов Campaign.
  • Campaign Statistics → Configs — один показатель с разбивкой по конфигам.
  • Campaign Statistics → Tags — один показатель с разбивкой по тегам всей Campaign.
  • Stats Summary — сводная административная страница. Её текущий интерфейс остаётся отдельным от publisher-статистики.
  • Raw Events — диагностический журнал всех runtime, server и VAST Wrapper событий.

На вкладках с несколькими сущностями чипсы работают так: без выбранных чипсов показываются все сущности; после выбора — только выбранные; после снятия всех снова отображаются все. Для chart и table можно выбирать отдельную группировку по часу или по дню.

12. Publisher-метрики

  • Requests — количество реальных попыток запросить тег: событие tag_request. Один запуск с тремя тегами даёт три Requests.
  • Filled Requests — количество Tag requests, которые дали хотя бы один impression: tag_filled. Для внутреннего pod из нескольких Ads считается один Filled Request.
  • Impressions — фактические рекламные показы: tag_impression.
  • Starts — начало воспроизведения Ads.
  • First Quartile / Midpoint / Third Quartile — достижение 25%, 50% и 75% длительности ролика.
  • Completes — ролики, дошедшие до полного завершения.
  • Clicks — переходы по click-through рекламы.
  • Skips — пропуски рекламы, если creative разрешает skip.
  • No Fill — неуспешные tag requests с кодами 303 или 1009.
  • Errors — другие ошибки тега, например 403 для несовместимого media asset.
  • Fill Rate = Filled Requests / Requests × 100.
  • CTR = Clicks / Impressions × 100.
  • Completion Rate = Completes / Starts × 100.
  • Error Rate = Errors / Requests × 100.
  • No Fill Rate = No Fill / Requests × 100.
Total-проценты рассчитываются взвешенно из суммарных числителей и знаменателей. Дневные проценты не складываются и не усредняются.

13. Raw events и hourly aggregates

Каждое событие сначала записывается в PlayerEvent. Завершённые дни агрегируются по часам в PlayerEventHourlyAggregate. Обе таблицы используют вертикальную event-модель: имя события хранится в поле event, а количество агрегата — в count.

Статистические страницы читают непересекающиеся диапазоны: свежие календарные дни из raw events, более старые — из hourly aggregates. Это предотвращает удвоение.

python manage.py verify_publisher_stats --date YYYY-MM-DD --config-id CONFIG_ID --strict
Команда сравнивает publisher-метрики raw и aggregate за один день. Успешная проверка заканчивается строкой «Raw and hourly aggregate metrics match.».

14. Диагностика и типичные результаты

  • 303 — Wrapper chain не вернул объявление; учитывается как No Fill конкретного тега.
  • 1009 — ответ не содержит валидных Ads; учитывается как No Fill.
  • 403 — linear assets найдены, но не подошли возможностям плеера; учитывается как Error.
  • Предупреждения браузера про partitioned cookies, fingerprinting protection или deprecated initMouseEvent() могут исходить из Google IMA и не всегда означают поломку Ads-Flow.
  • Если iframe не загружается, проверить CSP площадки: frame-src должен разрешать player.ads-flow.net.
  • Если ролик виден, но не кликается, проверить, не перекрывает ли iframe прозрачный слой родительской страницы и не отключены ли pointer events.

15. Рекомендуемый рабочий порядок

  1. Создать или проверить учётную запись Manager.
  2. Создать Campaign и назначить managers/admins.
  3. Создать Tags, указать VAST URL templates и доступные Campaigns.
  4. Создать Player Config, выбрать Campaign, owner и порядок Tags.
  5. Настроить Width, Height, Autoplay и Muted.
  6. Скопировать кнопку Iframe и передать код площадке.
  7. Проверить referrer, tag sequence и click-through на странице publisher-а.
  8. Проверить Config Statistics, Tags tab и Raw Events.
  9. После появления трафика сравнивать показатели с advertiser по Requests, Impressions, Completes, Clicks, No Fill и Errors.