09 Интеграция рекламы
Рекламный сервер отдаёт рекламу по нескольким маршрутам. Полный список пайплайнов и их параметров описан в dist/server/configs/config.yaml.
| Маршрут | Назначение |
|---|---|
/banner/{placement}/{action} |
Статический баннер: img — картинка, click — переход |
/native/{placement} |
Нативный формат (JSON) |
/dsp/{placement} |
RTB/DSP-запрос |
/inapp/{placement} |
Формат для мобильных приложений |
/tracker/{data}.gif |
Трекинг-пиксель |
/postback |
Приём постбеков от сетей |
Во всех примерах ниже https://ads.example.com — публичный адрес вашего рекламного сервера (порт 8071), а {placement} — числовой ID плейсмента из колонки ID в админке.
В
dist/server/configs/config.yamlдля output-плагиновwebиinappзадаётся параметрbase— публичный адрес сервера, который подставляется в ссылки трекинга. Укажите там свой домен.
Если сайт плейсмента выключен, сервер отвечает
200 OKс пустым телом — это значит «рекламы нет». Клиент должен трактовать такой ответ как отсутствие рекламы (noad) и ничего не показывать.
Баннер
Баннер добавляется как обычный HTML-элемент: картинка формируется на лету и оборачивается в ссылку перехода.
<a href="https://ads.example.com/banner/4/click">
<img src="https://ads.example.com/banner/4/img" width="350">
</a>
Размер тега img зависит от размеров картинок в рекламных кампаниях. Стилизовать элемент можно как угодно — главное, чтобы картинка была внутри ссылки. На баннер автоматически наносятся описание и маркировка рекламодателя.
Нативный формат
JSON доступен по адресу https://ads.example.com/native/4. Ответ — массив объектов:
[
{
"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?revenue={revenue}"],
"clicks": ["https://ads.example.com/tracker/....gif?revenue={revenue}"],
"data": "",
"network": "coffee",
"format": "banner",
"revenue": 1.5
}
]
Поля:
description— текст объявления;information— маркировка рекламы (для display-креативов);image— ссылка на изображение;target— целевая ссылка для перехода;impressions— трекинг-пиксели показа;clicks— трекинг-пиксели клика;data— произвольные данные сети (например, JSON сblockдля Yandex);network— источник рекламы (coffee,yandexи т. д.);format—bannerилиinterstitial;revenue— доход за показ (для сетей, подключённых через медиацию), опционально.
Для учёта статистики: вызовите все ссылки из impressions при показе и из clicks при клике. В трекер-ссылках есть макрос {revenue} — подставьте в него доход показа (для собственных креативов он не обязателен). Само объявление ведёт на 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: "4",
template: "horizontal" // "horizontal" | "horizontal-marker" | "default"
});
});
</script>
Виджет умеет показывать собственные (coffee) креативы и блоки Yandex: если сервер вернул network: "yandex", виджет подключает Yandex Ads SDK и использует data.block как идентификатор блока. При отключённом сайте (пустой ответ) контейнер остаётся пустым.
Скрипт запрашивает объявления с адреса
https://platform.ads.coffee. Для самостоятельного хостинга измените этот URL вserver/static/js/coffee.jsна адрес вашего сервера.
Мобильные приложения
Для Android есть SDK в каталоге sdk/android/ (модуль coffeesdk). Он умеет загружать объявление, показывать баннер в InAppAdView, интерстишел в полноэкранном диалоге и отправлять события показа и клика. Формат для приложений отдаётся сервером по маршруту /inapp/{placement}.
CoffeeAds.setBaseUrl("https://ads.example.com")
CoffeeAds.initialize(context) {
val loader = InAppAdLoader(context)
val request = InAppAdRequest.Builder(PLACEMENT_ID).build()
loader.loadAd(request, object : InAppAdLoadListener {
override fun onAdLoaded(ad: InAppAd) {
ad.setInAppAdEventListener(object : InAppAdEventListener {
override fun onAdClicked() { ad.target?.let { openTarget(it) } }
override fun onImpression(data: ImpressionData?) {}
})
if (ad.format?.equals("interstitial", ignoreCase = true) == true) {
InAppInterstitial.show(context, ad) { /* закрыт */ }
} else {
val binder = InAppAdViewBinder.Builder(adView).build()
ad.bindInAppAd(binder)
ad.fireImpressionTrackers()
}
}
override fun onAdFailedToLoad(error: AdRequestError) {
// Рекламы нет (noad) — ничего не показываем
}
})
}
Особенности:
- noad. Пустой ответ (
200 OKбез объявлений, в том числе для выключенного сайта) приводит кonAdFailedToLoad— ничего не рисуйте и не показывайте интерстишел. - Интерстишел. Клик в любом месте, кроме крестика, открывает
target; трекинг клика отправляется автоматически. - Yandex. SDK поддерживает креативы сетей, включая Yandex Ads через медиацию (идентификатор блока передаётся в поле
data).
Постбеки
Маршрут /postback принимает уведомления о конверсиях от партнёрских сетей. Если сеть поддерживает постбеки, укажите в её кабинете URL вашего сервера — так конверсии будут попадать в общую аналитику.