SDK правил автопаузы и скриптов
Справочник того, что доступно внутри кода правила автопаузы и пользовательского скрипта: поля объекта ad, функции паузы и возврата, селекторы для выборки объявлений. Подписи для всех полей с описаниями также доступны прямо в редакторе правил — в боковой панели Справочник ключей ad.* (поиск по имени и описанию).
Это Server SDK — команды, которые выполняются на сервере Qubix, в отличие от Browser SDK в браузере посетителя. Server SDK синхронный: sql, ctx.fetch и состояние возвращают значение сразу — без await и Promise.
Объект ad
В правиле автопаузы вы получаете единственный объект ad — это объявление, для которого выполняется проверка. Через него вы читаете все метрики и атрибуты. Все доступные поля сгруппированы по области.
| Группа | Префикс поля | Что внутри |
|---|---|---|
| Ad | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Метрики и атрибуты самого объявления |
| Creative | ad.creo_* | Метрики по креативу (все объявления с этим креативом) |
| Geo | ad.geo_* | Метрики по стране |
| Offer | ad.offer_* | Метрики и параметры оффера (выплата, кап) |
| Network | ad.network_* | Метрики по партнёрке |
| Previous period | ad.prev_* | Те же метрики за предыдущий период (для сравнения) |
Полный список метрик, временных окон (_1h…_total) и смысл каждого префикса — в разделе Метрики и колонки.
Обращение к несуществующему полю (ad.something_wrong) сразу прерывает правило с ошибкой. Сверяйте имена со справочником в редакторе.
Пауза
Три функции — по области. Объявление, адсет и кампания.
| Функция | Действие |
|---|---|
pauseAd(duration, reason?) | Поставить на паузу текущее объявление |
pauseAdset({ adsetId, duration, reason? }) | Поставить на паузу адсет |
pauseCampaign({ campaignId, duration, reason? }) | Поставить на паузу кампанию |
Для pauseAd достаточно передать длительность строкой; для адсета и кампании требуется форма объекта с явным adsetId / campaignId.
Длительности (duration):
| Значение | Смысл |
|---|---|
6h / 12h / 24h | Пауза на N часов |
next_day_target_geo | До начала следующего дня по времени целевой страны |
next_day_ad_account | До начала следующего дня по времени рекламного кабинета |
permanent | Постоянная пауза |
while_matches | Пока выполняется условие правила |
reason — необязательный комментарий, который попадает в лог. Если опущен — подставляется имя правила.
Возврат
| Функция | Действие |
|---|---|
activateAd(reason?) | Вернуть в работу текущее объявление |
activateAdset({ adsetId, reason? }) | Вернуть в работу адсет |
activateCampaign({ campaignId, reason? }) | Вернуть в работу кампанию |
Соседние объявления
Внутри правила можно смотреть на другие объявления того же адсета или кампании — например, чтобы остановить весь адсет, если просело лишь одно объявление.
| Функция | Возвращает |
|---|---|
getAd(id) | Объявление по его ad_id |
getAdset() | Все объявления адсета текущего объявления |
getCampaign() | Все объявления кампании текущего объявления |
Также доступны console.log / console.warn / console.error для отладочного вывода и skipNextRules() — пропустить оставшиеся правила для этого объявления.
Селекторы QubixApp (для скриптов)
В пользовательских скриптах доступен объект QubixApp — он выбирает объявления, адсеты и кампании по условиям. У каждого выбранного элемента есть своя статистика и методы паузы.
| Метод | Возвращает выборку |
|---|---|
QubixApp.ads() | Объявления |
QubixApp.adsets() | Адсеты |
QubixApp.campaigns() | Кампании |
Методы выборки (цепочкой):
| Метод | Что делает |
|---|---|
.withCondition(sql) | Фильтр по условию |
.filter(fn) | Фильтр функцией |
.orderBy(field, dir) | Сортировка ('asc' / 'desc') |
.withLimit(n) | Ограничить число элементов |
.get() | Получить массив элементов |
.first() | Получить первый элемент |
Методы элемента:
| Метод | Действие |
|---|---|
.pause({ duration, reason? }) | Пауза |
.activate({ reason? }) | Вернуть в работу |
.getStatsFor(period) | Метрики за окно ('1h'…'total') |
.getAds() | Объявления внутри адсета / кампании |
.getAdsets() | Адсеты внутри кампании |
getStatsFor возвращает набор метрик за выбранное окно: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Контекст скрипта
В скриптах дополнительно доступен объект ctx.
| Поле / метод | Назначение |
|---|---|
ctx.state.get/set/delete/keys | Сохранение состояния между запусками |
ctx.fetch(url, opts?) | HTTP-запрос (хост должен быть в allowlist, см. JavaScript в настройках) |
ctx.now() | Текущее время |
ctx.script | Информация о текущем скрипте |
Объект ctx (включая ctx.fetch) существует только в скриптах — внутри правил автопаузы он недоступен. И даже в скриптах ctx.fetch работает только при реальном запуске на сервере: в тестовом прогоне в браузере сетевые вызовы отключены, поэтому проверяйте через реальный запуск.
Общее хранилище
Кроме личного ctx.state, есть общее хранилище ctx.state.global — оно видно всем скриптам, правилам и обработчикам сайта сразу.
| Метод | Действие |
|---|---|
ctx.state.global.get(key) | Прочитать значение |
ctx.state.global.keys() | Список ключей |
ctx.state.global.set(key, value) | Записать значение |
ctx.state.global.delete(key) | Удалить значение |
Читать общее хранилище может любой скрипт или правило. Записывать (set / delete) разрешено только из скрипта или правила, которое принадлежит администратору — иначе запись вернёт ошибку. Удобно для общих справочников: администратор кладёт значение один раз, остальные читают.
ctx.fetch: таймаут по умолчанию 10 секунд (максимум 30), ответ до 1 МБ, не больше 20 запросов за один прогон.sql: один запрос возвращает не больше нескольких тысяч строк — точный потолок задаёт администратор в настройках. Для больших выборок агрегируйте прямо в запросе.
Точные значения лимитов настраиваются в Система → вкладка JavaScript.
Read-only sql
Тегированный шаблон sql\SELECT …`выполняет read-only запрос данных в рамках прав владельца. Он доступен **и в правилах автопаузы (Britva), и в пользовательских скриптах** — при условии, что включена соответствующая системная настройка. В тестовом прогоне в браузере он отключён (как иctx.fetch), поэтому проверяйте правило или скрипт, использующие sql`, через реальный запуск на сервере.
Полный список таблиц и колонок, доступных запросу, — в Таблицах для запросов sql.