Менеджер и publisher-интеграция

1. Что предоставляет Ads-Flow

Ads-Flow выдаёт готовый HTML iframe, который загружает рекламный runtime по public key. Площадке не требуется хранить VAST URL или реализовывать Google IMA самостоятельно.

Config определяет компанию, набор рекламных тегов, их порядок, autoplay, muted и размер iframe.
Плеер автоматически получает домен страницы размещения и подставляет его в {referrer}, если такой макрос есть в Tag.
Плеер проходит все активные теги конфига и собирает статистику по каждому.
Click-through открывается механизмом рекламного creative / Google IMA.

2. Компания и доступ Manager

Manager видит только Campaigns, в которые он добавлен, и собственные Player Configs. Если доступна одна Campaign, она подставляется автоматически. Если Campaigns несколько, необходимо выбрать нужную при создании конфига.

Доступные Tags зависят от выбранной Campaign. При смене Campaign текущая очередь тегов очищается и должна быть собрана заново.

3. Создание конфига

Открыть Player Configs и нажать Create Config.
Указать Name и при необходимости Description.
Выбрать Campaign.
Добавить доступные Tags и расставить их перетаскиванием в нужном порядке.
Указать Width и Height рекламного iframe.
Настроить Active, Autoplay и Muted.
Сохранить Config. Public key и iframe HTML будут сгенерированы автоматически.

Active OFF — публичный iframe конфига не работает.
Autoplay ON — плеер начинает запрос после попадания iframe в требуемую область видимости.
Autoplay OFF — запуск требует пользовательского действия.
Muted ON — старт без звука; рекомендуется для autoplay.

4. Установка iframe

В строке конфига нажмите Iframe. В буфер обмена попадёт готовый однострочный HTML.

<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 не должна публиковаться как обычная ссылка: она предназначена для iframe.

Площадка может сделать родительский контейнер уже — iframe уменьшится до доступной ширины.
Значение max-width не позволяет iframe стать шире Width.
Пропорции задаются Width / Height через aspect-ratio.
После изменения Width или Height код нужно скопировать заново.
После изменения Autoplay или Muted повторное копирование не требуется.

5. Referrer площадки

Referrer в Ads-Flow — домен страницы размещения, например news.example.com. Он определяется внутри iframe и передаётся backend-у вместе с запросом конкретного Tag.

В VAST URL template макрос {referrer} заменяется на домен в момент запроса.
В БД остаётся исходный шаблон, поэтому один Tag можно использовать у разных publisher-ов.
Если площадка полностью запрещает передачу referrer, Tag с обязательным макросом не сможет сформировать корректный запрос.

6. Поведение плеера

Iframe загружает Config по public key.
Runtime получает referrer и настройки Autoplay / Muted.
Каждый активный Tag запрашивается отдельно в порядке конфига.
No-fill или ошибка одного Tag не останавливает очередь.
Если Tag вернул один или несколько Ads, они полностью воспроизводятся.
После завершения Tag плеер переходит к следующему, даже если текущий был успешным.
После последнего Tag общая playback session завершается.

В out-stream режиме видимые элементы управления по умолчанию скрыты. Ролик остаётся кликабельным, если creative содержит click-through. При click-through IMA может кратковременно отправить pause, после чего Ads-Flow автоматически возобновляет ролик.

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

7. Как читать статистику

General показывает общие показатели конфига.
Tags показывает один выбранный показатель отдельно по каждому Tag.
Campaign → General объединяет доступные конфиги компании.
Campaign → Configs сравнивает конфиги.
Campaign → Tags сравнивает теги.

Диапазон дат общий для графика и таблицы. Группировку графика и таблицы можно менять независимо. На вкладках Configs и Tags без выбранных чипсов показываются все линии.

8. Значение показателей

Requests — сколько Tag requests реально выполнил плеер. При трёх тегах один запуск iframe обычно даёт три Requests.
Filled Requests — сколько Tag requests дали хотя бы один рекламный показ.
Impressions — количество показанных Ads. Оно может быть выше Filled Requests, если один Tag вернул внутренний ad pod.
Starts — количество начавшихся роликов.
First Quartile / Midpoint / Third Quartile — сколько роликов дошло до 25%, 50% и 75%.
Completes — полные просмотры.
Clicks — click-through переходы.
No Fill — Tag requests без доступного объявления.
Errors — технические или media-ошибки.

Fill Rate = Filled Requests / Requests × 100.
CTR = Clicks / Impressions × 100.
Completion Rate = Completes / Starts × 100.

Total для процентных показателей является взвешенным. Например, общий Fill Rate рассчитывается как сумма Filled Requests за период, делённая на сумму Requests, а не как среднее дневных процентов.

9. Проверка интеграции

Вставить сгенерированный iframe в тестовое рекламное место страницы.
Открыть DevTools → Network и проверить запрос /outstream/pub_.../.
Проверить отдельные запросы /vast-pod/ для каждой позиции Tag.
Убедиться, что referrer равен домену площадки.
Проверить воспроизведение, click-through и переход к следующему Tag после complete/error.
Открыть Config Statistics и Raw Events.

Для ожидаемой очереди «нерабочий → рабочий → нерабочий» в Raw Events должны быть tag_failed, затем tag_filled / tag_completed, затем снова tag_failed, после чего ad_pod_complete.

10. Частые проблемы

Iframe не загружается — проверить Active у Config и Campaign, а также CSP frame-src площадки.
Реклама не стартует — проверить referrer, доступность Tags и Raw Events.
Код 303 или 1009 — конкретный Tag не дал рекламу; плеер должен перейти дальше.
Код 403 — Tag вернул linear creative, но media asset не подошёл браузеру.
Ролик не кликается — проверить, не перекрыт ли iframe элементами страницы и есть ли click-through в самом creative.
После окончания остаётся пустое место — это размер внешнего slot; его скрывает publisher.
Autoplay со звуком блокируется — включить Muted или использовать запуск по действию пользователя.

11. Границы ответственности

Ads-Flow отвечает за загрузку Config, получение referrer, запрос Tags, воспроизведение Ads внутри iframe и собственную статистику.
Publisher отвечает за место вставки, размеры родительского контейнера, CSP, видимость рекламного slot и его удаление/схлопывание.
Advertiser/ad server отвечает за содержимое VAST, доступные creatives, click-through и свои tracking pixels.

Небольшие расхождения между Ads-Flow и advertiser возможны из-за сетевых ошибок, блокировщиков, разных правил подсчёта и недоставленных pixels. Для сравнения в первую очередь используйте Requests, Filled Requests, Impressions, Completes, Clicks, No Fill и Errors за одинаковый период.