Колбеки для рекламного стека

Если плеер CPMArena стоит в чужом рекламном стеке партнёра (партнёр ротирует один слот между несколькими плеерами), ему нужно машинно знать исход по слоту: иначе показ не зачтётся или слот останется пустым. Для этого плеер отдаёт наружу три сигнала — колбеки.

📡 Три сигнала

✅ Гарантии контракта

1. На один цикл показа слота — ровно один терминальный сигнал: либо adRender, либо adAbsence. Повторов нет.
2. adAbsence терминальный: мы действительно освобождаем слот и больше не пытаемся его заполнить. Это защита партнёра от наложения двух реклам в одном слоте.
3. Если после показа плеер окончательно прекратил работу — приходит ещё один adAbsence уже по новому циклу (слот снова свободен). Это единственное исключение из правила «один сигнал».
4. Если рекламы нет и вместо неё показана заглушка — это тоже adAbsence (слот не считается занятым).
5. Поздняя подписка получает уже отданный сигнал — не нужно гадать, успел ли ваш скрипт загрузиться.
6. Дедлайн ответа настраивается на стороне блока: если за отведённое время рекламы нет — приходит adAbsence. Конкретное значение согласуем при подключении, чтобы оно совпало с вашей ротацией.

🔌 Два способа подключения

Партнёр выбирает удобный способ — оба дают одни и те же сигналы.

Способ 1. Мы вызываем ваши функции

Сообщите нам имена функций — мы пропишем их в настройках блока в админке. Писать код на сайте не нужно. Путь функции — имена через точку, до пяти уровней, например myAdAPI.onAdRender.

Способ 2. Подписка на стороне сайта

Подпишитесь через очередь команд cpmArenaCb и CPM.on — так же, как при программной вставке блока:

window.cpmArenaCb = window.cpmArenaCb || [];
cpmArenaCb.push(function () {
  CPM.on("adRender",  function (payload) { myAdAPI.onAdRender(payload);  });
  CPM.on("adAbsence", function (payload) { myAdAPI.onAdAbsence(payload); });
  CPM.on("adClose",   function (payload) { myAdAPI.onAdClose(payload);   });
});

Отписаться можно через CPM.off — передайте тот же обработчик, что передавали в CPM.on:

function onRender(payload) {
  // обработка
}

CPM.on("adRender", onRender);
// ...
CPM.off("adRender", onRender);

📦 Что получает обработчик

Каждый обработчик получает объект с полями:

Причины reason нейтральные. Чаще всего вы увидите что-то вроде:

• рекламы не нашлось;
• вышел дедлайн;
• блок не подходит под устройство;
• исчерпан лимит показов;
• блок вставлен в два места сразу;
• блок выключен;
• слот освободился.

⚠️ Ограничения при включённых колбеках

Эти ограничения включаются автоматически — партнёру важно о них знать:

• Ленивая загрузка (lazy load) для блока с колбеками отключается: ответ по слоту должен приходить сразу.
• Повторное открытие плеера после закрытия (restart on close) для блока с колбеками запрещено: нельзя вернуться в слот, о котором мы уже сказали «свободен».
• Несколько копий одного блока на странице (например InRead в бесконечной прокрутке) в этой версии с колбеками не поддерживается.

🔄 Принудительный перезапрос слота

Если нужно открыть новый цикл и получить новый сигнал, вызовите CPM.render с force: true:

CPM.render({
  block: "site_XXXXXX_1",
  container: "#slot",
  force: true
});

📚 Связанные разделы

• Установка кода плеера — загрузчик, контейнеры блоков, CPM.render()
• Форматы рекламы — sticky, InRead, fullscreen
• Контакты — если нужно включить колбеки в блоке