09 Интеграция рекламы

Рекламный сервер отдаёт рекламу по нескольким маршрутам. Полный список пайплайнов и их параметров описан в dist/server/configs/config.yaml.

Маршрут	Назначение
`/banner/{block}/{action}`	Статический баннер: `img` — картинка, `click` — переход
`/native/{block}`	Нативный формат (JSON)
`/dsp/{block}`	RTB/DSP-запрос
`/inapp/{block}`	Формат для мобильных приложений
`/tracker/{data}.gif`	Трекинг-пиксель
`/postback`	Приём постбеков от сетей

Во всех примерах ниже https://ads.example.com — публичный адрес вашего рекламного сервера (порт 8071). Идентификатор блока ({block}) показан на странице редактирования блока в админке.

В dist/server/configs/config.yaml для output-плагинов web задаётся параметр base — публичный адрес сервера, который подставляется в ссылки трекинга. Укажите там свой домен.

Баннер

Баннер добавляется как обычный HTML-элемент: картинка формируется на лету и оборачивается в ссылку перехода.

<a href="https://ads.example.com/banner/8v0g374le06u49d/click">
  <img src="https://ads.example.com/banner/8v0g374le06u49d/img" width="350">
</a>

Размер тега img зависит от размеров картинок в рекламных кампаниях. Стилизовать элемент можно как угодно — главное, чтобы картинка была внутри ссылки. На баннер автоматически наносятся описание и маркировка рекламодателя.

Нативный формат

JSON доступен по адресу https://ads.example.com/native/<block>. Ответ — массив объектов:

[
  {
    "description": "Веб-разработка на Go",
    "information": "Реклама. Рекламодатель ООО «Пример», ИНН 0000000000. erid 2SDnjeP817J",
    "image": "https://ads.example.com/files/course.png",
    "target": "https://advertiser.example/landing",
    "impressions": ["https://ads.example.com/tracker/....gif"],
    "clicks": ["https://ads.example.com/tracker/....gif"],
    "network": "coffee"
  }
]

Поля:

description — текст объявления;
information — маркировка рекламы;
image — ссылка на изображение;
target — целевая ссылка для перехода;
impressions — трекинг-пиксели показа;
clicks — трекинг-пиксели клика;
network — источник рекламы (для сетей, подключённых через медиацию).

Для учёта статистики: вызовите все ссылки из impressions при показе и из clicks при клике. Само объявление ведёт на target.

JS-виджет

Для сайтов есть готовый скрипт server/static/js/coffee.js. Он сам загружает объявление, рендерит его в выбранный контейнер и отправляет трекинг:

<div id="ads-container"></div>
<script src="https://ads.example.com/static/js/coffee.js" async></script>
<script>
  window.adsCoffeeCb = window.adsCoffeeCb || [];
  window.adsCoffeeCb.push(function () {
    window.adsCoffee.render({
      renderTo: "ads-container",
      placementId: "8v0g374le06u49d",
      template: "horizontal" // или "horizontal-marker" / "default"
    });
  });
</script>

Мобильные приложения

Для Android есть SDK в каталоге sdk/android/ (модуль coffeesdk). Он умеет загружать объявление, показывать его в InAppAdView и отправлять события показа и клика. Формат для приложений отдаётся сервером по маршруту /inapp/{block}.

Постбеки

Маршрут /postback принимает уведомления о конверсиях от партнёрских сетей. Если сеть поддерживает постбеки, укажите в её кабинете URL вашего сервера — так конверсии будут попадать в общую аналитику.