SDK für Auto-Regeln und Skripte
Eine Referenz dafür, was innerhalb des Codes einer Auto-Pause-Regel und eines Benutzerskripts verfügbar ist: die Felder des Objekts ad, die Funktionen zum Pausieren und Fortsetzen sowie die Selektoren zum Auswählen von Anzeigen. Beschriftungen für alle Felder mit Erläuterungen sind auch direkt im Regeleditor verfügbar — im seitlichen Panel ad.*-Schlüsselreferenz (Suche nach Name und Beschreibung).
Dies ist das Server SDK — Befehle, die auf dem Qubix-Server laufen, im Gegensatz zum Browser SDK, das im Browser des Besuchers läuft. Das Server SDK ist synchron: sql, ctx.fetch und State geben einen Wert direkt zurück — kein await oder Promises.
Das ad-Objekt
In einer Auto-Pause-Regel erhalten Sie ein einzelnes ad-Objekt — das ist die Anzeige, für die die Prüfung läuft. Über es lesen Sie alle Metriken und Attribute. Alle verfügbaren Felder sind nach Geltungsbereich gruppiert.
| Gruppe | Feld-Präfix | Was darin steckt |
|---|---|---|
| Anzeige | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Metriken und Attribute der Anzeige selbst |
| Creative | ad.creo_* | Metriken nach Creative (alle Anzeigen mit diesem Creative) |
| Geo | ad.geo_* | Metriken nach Land |
| Offer | ad.offer_* | Metriken und Parameter des Offers (Auszahlung, Cap) |
| Network | ad.network_* | Metriken nach Network |
| Vorheriger Zeitraum | ad.prev_* | Dieselben Metriken für den vorherigen Zeitraum (zum Vergleich) |
Die vollständige Liste der Metriken, Zeitfenster (_1h…_total) und die Bedeutung jedes Präfixes — im Abschnitt Metriken und Spalten.
Der Zugriff auf ein nicht existierendes Feld (ad.something_wrong) bricht die Regel sofort mit einem Fehler ab. Prüfen Sie Namen gegen die Referenz im Editor.
Pause
Drei Funktionen — nach Geltungsbereich. Die Anzeige, die Anzeigengruppe und die Kampagne.
| Funktion | Aktion |
|---|---|
pauseAd(duration, reason?) | Die aktuelle Anzeige pausieren |
pauseAdset({ adsetId, duration, reason? }) | Die Anzeigengruppe pausieren |
pauseCampaign({ campaignId, duration, reason? }) | Die Kampagne pausieren |
Bei pauseAd genügt es, die Dauer als String zu übergeben; für die Anzeigengruppe und Kampagne ist die Objektform mit einem expliziten adsetId / campaignId erforderlich.
Dauern (duration):
| Wert | Bedeutung |
|---|---|
6h / 12h / 24h | Pause für N Stunden |
next_day_target_geo | Bis zum Beginn des nächsten Tages in der Zeit des Ziellandes |
next_day_ad_account | Bis zum Beginn des nächsten Tages in der Zeit des Werbekontos |
permanent | Eine permanente Pause |
while_matches | Solange die Regelbedingung erfüllt ist |
reason ist ein optionaler Kommentar, der in das Log eingeht. Wird er weggelassen, wird der Regelname eingesetzt.
Fortsetzen
| Funktion | Aktion |
|---|---|
activateAd(reason?) | Die aktuelle Anzeige fortsetzen |
activateAdset({ adsetId, reason? }) | Die Anzeigengruppe fortsetzen |
activateCampaign({ campaignId, reason? }) | Die Kampagne fortsetzen |
Benachbarte Anzeigen
Innerhalb einer Regel können Sie andere Anzeigen derselben Anzeigengruppe oder Kampagne betrachten — zum Beispiel, um die ganze Anzeigengruppe zu stoppen, wenn nur eine Anzeige eingebrochen ist.
| Funktion | Gibt zurück |
|---|---|
getAd(id) | Eine Anzeige über ihre ad_id |
getAdset() | Alle Anzeigen der Anzeigengruppe der aktuellen Anzeige |
getCampaign() | Alle Anzeigen der Kampagne der aktuellen Anzeige |
Ebenfalls verfügbar sind console.log / console.warn / console.error für Debug-Ausgaben und skipNextRules() — die übrigen Regeln für diese Anzeige überspringen.
QubixApp-Selektoren (für Skripte)
In Benutzerskripten ist das Objekt QubixApp verfügbar — es wählt Anzeigen, Anzeigengruppen und Kampagnen nach Bedingungen aus. Jedes ausgewählte Element hat eigene Statistik- und Pause-Methoden.
| Methode | Gibt eine Auswahl zurück von |
|---|---|
QubixApp.ads() | Anzeigen |
QubixApp.adsets() | Anzeigengruppen |
QubixApp.campaigns() | Kampagnen |
Auswahl-Methoden (verkettbar):
| Methode | Was sie tut |
|---|---|
.withCondition(sql) | Nach einer Bedingung filtern |
.filter(fn) | Mit einer Funktion filtern |
.orderBy(field, dir) | Sortieren ('asc' / 'desc') |
.withLimit(n) | Die Anzahl der Elemente begrenzen |
.get() | Ein Array von Elementen erhalten |
.first() | Das erste Element erhalten |
Element-Methoden:
| Methode | Aktion |
|---|---|
.pause({ duration, reason? }) | Pausieren |
.activate({ reason? }) | Fortsetzen |
.getStatsFor(period) | Metriken für ein Fenster ('1h'…'total') |
.getAds() | Anzeigen innerhalb einer Anzeigengruppe / Kampagne |
.getAdsets() | Anzeigengruppen innerhalb einer Kampagne |
getStatsFor gibt einen Satz von Metriken für das ausgewählte Fenster zurück: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Skript-Kontext
In Skripten ist zusätzlich das Objekt ctx verfügbar.
| Feld / Methode | Zweck |
|---|---|
ctx.state.get/set/delete/keys | Zustand zwischen Ausführungen erhalten |
ctx.fetch(url, opts?) | Eine HTTP-Anfrage (der Host muss in der Erlaubnisliste sein, siehe JavaScript in den Einstellungen) |
ctx.now() | Die aktuelle Zeit |
ctx.script | Informationen über das aktuelle Skript |
Das Objekt ctx (einschließlich ctx.fetch) existiert nur in Skripten — es ist nicht innerhalb von Auto-Pause-Regeln verfügbar. Und selbst in Skripten funktioniert ctx.fetch nur in einer echten Ausführung auf dem Server: in einer Browser-Testausführung sind Netzwerkaufrufe deaktiviert, prüfen Sie es also über eine echte Ausführung.
Gemeinsamer State
Neben dem privaten ctx.state gibt es einen gemeinsamen Speicher ctx.state.global, der für jedes Skript, jede Regel und jeden Site-Handler gleichzeitig sichtbar ist.
| Methode | Aktion |
|---|---|
ctx.state.global.get(key) | Einen Wert lesen |
ctx.state.global.keys() | Die Schlüssel auflisten |
ctx.state.global.set(key, value) | Einen Wert schreiben |
ctx.state.global.delete(key) | Einen Wert löschen |
Jedes Skript oder jede Regel kann den gemeinsamen Speicher lesen. Schreiben (set / delete) ist nur aus einem Skript oder einer Regel erlaubt, die einem Administrator gehört — andernfalls wirft der Schreibvorgang einen Fehler. Praktisch für gemeinsame Nachschlagewerte: der Administrator schreibt einen Wert einmal, alle anderen lesen ihn.
ctx.fetch: ein Timeout von 10 Sekunden standardmäßig (30 maximal), eine Antwort bis zu 1 MB, nicht mehr als 20 Anfragen pro Ausführung.sql: eine einzelne Abfrage gibt höchstens einige Tausend Zeilen zurück — der Administrator legt die genaue Obergrenze in den Einstellungen fest. Bei großen Selektionen direkt in der Abfrage aggregieren.
Die genauen Grenzwerte werden unter System → Registerkarte JavaScript konfiguriert.
Schreibgeschütztes sql
Das getaggte Template sql\SELECT …`führt eine schreibgeschützte Datenabfrage innerhalb der Berechtigungen des Eigentümers aus. Es ist **sowohl in Auto-Pause-Regeln (Britva) als auch in Benutzerskripten** verfügbar — sofern die entsprechende Systemeinstellung aktiviert ist. In einer Browser-Testausführung ist es deaktiviert (wiectx.fetch), prüfen Sie eine sql`-nutzende Regel oder ein Skript also über eine echte Ausführung auf dem Server.
Die vollständige Liste der Tabellen und Spalten, die eine Abfrage erreichen kann, finden Sie unter Tabellen für sql-Abfragen.