SDK reguł automatycznych i skryptów
Dokumentacja tego, co jest dostępne wewnątrz kodu reguły automatycznego wstrzymywania oraz skryptu użytkownika: pola obiektu ad, funkcje do wstrzymywania i wznawiania oraz selektory do wybierania reklam. Podpisy wszystkich pól wraz z opisami są również dostępne bezpośrednio w edytorze reguł — w panelu bocznym Dokumentacja kluczy ad.* (wyszukiwanie po nazwie i opisie).
To jest Server SDK — polecenia działające na serwerze Qubix, w odróżnieniu od Browser SDK, który działa w przeglądarce odwiedzającego. Server SDK jest synchroniczny: sql, ctx.fetch i stan zwracają wartość bezpośrednio — bez await ani Promises.
Obiekt ad
W regule automatycznego wstrzymywania otrzymuje Pan/Pani pojedynczy obiekt ad — to reklama, dla której uruchamiane jest sprawdzenie. Za jego pośrednictwem odczytuje Pan/Pani wszystkie metryki i atrybuty. Wszystkie dostępne pola są pogrupowane według zakresu.
| Grupa | Prefiks pola | Co zawiera |
|---|---|---|
| Reklama | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Metryki i atrybuty samej reklamy |
| Kreatyw | ad.creo_* | Metryki według kreatywu (wszystkie reklamy z tym kreatywem) |
| Geo | ad.geo_* | Metryki według kraju |
| Oferta | ad.offer_* | Metryki i parametry oferty (wypłata, cap) |
| Sieć | ad.network_* | Metryki według sieci |
| Poprzedni okres | ad.prev_* | Te same metryki za poprzedni okres (do porównania) |
Pełna lista metryk, okien czasowych (_1h…_total) oraz znaczenie każdego prefiksu — w sekcji Metryki i kolumny.
Odwołanie się do nieistniejącego pola (ad.something_wrong) natychmiast przerywa regułę z błędem. Sprawdzaj nazwy względem dokumentacji w edytorze.
Wstrzymanie
Trzy funkcje — według zakresu. Reklama, zestaw reklam oraz kampania.
| Funkcja | Działanie |
|---|---|
pauseAd(duration, reason?) | Wstrzymaj bieżącą reklamę |
pauseAdset({ adsetId, duration, reason? }) | Wstrzymaj zestaw reklam |
pauseCampaign({ campaignId, duration, reason? }) | Wstrzymaj kampanię |
Dla pauseAd wystarczy przekazać czas trwania jako ciąg znaków; dla zestawu reklam i kampanii wymagana jest forma obiektu z jawnym adsetId / campaignId.
Czasy trwania (duration):
| Wartość | Znaczenie |
|---|---|
6h / 12h / 24h | Wstrzymanie na N godzin |
next_day_target_geo | Do początku następnego dnia w czasie kraju docelowego |
next_day_ad_account | Do początku następnego dnia w czasie konta reklamowego |
permanent | Wstrzymanie na stałe |
while_matches | Dopóki warunek reguły jest spełniony |
reason to opcjonalny komentarz, który trafia do logu. Jeśli zostanie pominięty, podstawiana jest nazwa reguły.
Wznowienie
| Funkcja | Działanie |
|---|---|
activateAd(reason?) | Wznów bieżącą reklamę |
activateAdset({ adsetId, reason? }) | Wznów zestaw reklam |
activateCampaign({ campaignId, reason? }) | Wznów kampanię |
Sąsiednie reklamy
Wewnątrz reguły można spojrzeć na inne reklamy w tym samym zestawie reklam lub kampanii — na przykład, aby zatrzymać cały zestaw reklam, jeśli spadła tylko jedna reklama.
| Funkcja | Zwraca |
|---|---|
getAd(id) | Reklamę według jej ad_id |
getAdset() | Wszystkie reklamy w zestawie reklam bieżącej reklamy |
getCampaign() | Wszystkie reklamy w kampanii bieżącej reklamy |
Dostępne są również console.log / console.warn / console.error do wyjścia debugowego oraz skipNextRules() — pomiń pozostałe reguły dla tej reklamy.
Selektory QubixApp (dla skryptów)
W skryptach użytkownika dostępny jest obiekt QubixApp — wybiera on reklamy, zestawy reklam i kampanie według warunków. Każdy wybrany element ma własne statystyki oraz metody wstrzymywania.
| Metoda | Zwraca wybór |
|---|---|
QubixApp.ads() | Reklam |
QubixApp.adsets() | Zestawów reklam |
QubixApp.campaigns() | Kampanii |
Metody wyboru (łączone w łańcuch):
| Metoda | Co robi |
|---|---|
.withCondition(sql) | Filtruje według warunku |
.filter(fn) | Filtruje za pomocą funkcji |
.orderBy(field, dir) | Sortuje ('asc' / 'desc') |
.withLimit(n) | Ogranicza liczbę elementów |
.get() | Pobiera tablicę elementów |
.first() | Pobiera pierwszy element |
Metody elementu:
| Metoda | Działanie |
|---|---|
.pause({ duration, reason? }) | Wstrzymaj |
.activate({ reason? }) | Wznów |
.getStatsFor(period) | Metryki za okno ('1h'…'total') |
.getAds() | Reklamy wewnątrz zestawu reklam / kampanii |
.getAdsets() | Zestawy reklam wewnątrz kampanii |
getStatsFor zwraca zestaw metryk dla wybranego okna: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Kontekst skryptu
W skryptach dodatkowo dostępny jest obiekt ctx.
| Pole / metoda | Przeznaczenie |
|---|---|
ctx.state.get/set/delete/keys | Utrwalanie stanu między uruchomieniami |
ctx.fetch(url, opts?) | Żądanie HTTP (host musi znajdować się na allowliście, zob. JavaScript w ustawieniach) |
ctx.now() | Bieżący czas |
ctx.script | Informacje o bieżącym skrypcie |
Obiekt ctx (w tym ctx.fetch) istnieje wyłącznie w skryptach — nie jest dostępny wewnątrz reguł automatycznego wstrzymywania. A nawet w skryptach ctx.fetch działa tylko w rzeczywistym uruchomieniu na serwerze: w testowym uruchomieniu w przeglądarce wywołania sieciowe są wyłączone, dlatego należy zweryfikować to za pomocą rzeczywistego uruchomienia.
Współdzielony stan
Oprócz prywatnego ctx.state istnieje wspólny magazyn ctx.state.global, widoczny dla każdego skryptu, reguły i procedury obsługi witryny jednocześnie.
| Metoda | Działanie |
|---|---|
ctx.state.global.get(key) | Odczyt wartości |
ctx.state.global.keys() | Lista kluczy |
ctx.state.global.set(key, value) | Zapis wartości |
ctx.state.global.delete(key) | Usunięcie wartości |
Każdy skrypt lub reguła mogą odczytać wspólny magazyn. Zapis (set / delete) jest dozwolony tylko ze skryptu lub reguły należących do administratora — w przeciwnym razie zapis zgłasza błąd. Przydatne do wspólnych słowników: administrator zapisuje wartość raz, wszyscy pozostali ją odczytują.
ctx.fetch: domyślnie limit czasu wynosi 10 sekund (maksymalnie 30), odpowiedź do 1 MB, nie więcej niż 20 żądań na uruchomienie.sql: pojedyncze zapytanie zwraca co najwyżej kilka tysięcy wierszy — dokładną granicę administrator ustawia w ustawieniach. W przypadku dużych zbiorów należy agregować bezpośrednio w zapytaniu.
Dokładne wartości limitów są konfigurowane w System → zakładka JavaScript.
Tylko do odczytu sql
Tagowany szablon sql\SELECT …`uruchamia zapytanie o dane tylko do odczytu w granicach uprawnień właściciela. Jest dostępny **zarówno w regułach automatycznego wstrzymywania (Britva), jak i w skryptach użytkownika** — pod warunkiem, że odpowiednie ustawienie systemowe jest włączone. W testowym uruchomieniu w przeglądarce jest wyłączony (jakctx.fetch), dlatego regułę lub skrypt korzystający z sql` należy zweryfikować za pomocą rzeczywistego uruchomienia na serwerze.
Pełna lista tabel i kolumn dostępnych w zapytaniu znajduje się w artykule Tabele dla zapytań sql.