Ein Skript schreiben
Der Skript-Editor ist der Arbeitsbereich, in dem Sie Code schreiben, ihn an Live-Daten testen und den Zeitplan einrichten. Der Bildschirm ist in drei Teile aufgeteilt: links — der KI-Assistent, in der Mitte — der Code-Editor und die Konsole, rechts — das Einstellungspanel (Metadaten, Zeitplan, Zustand, Ausführungsverlauf).
Wie man ein Skript erstellt
- Öffnen Sie den Bereich Scripts und klicken Sie auf + Script erstellen. Der Editor öffnet sich mit einer Code-Vorlage.
- Füllen Sie im rechten Panel im Abschnitt Metadaten den Name und die Beschreibung des Skripts aus.
- Schreiben Sie im zentralen Editor den Körper der Funktion
main()— genau das, was das Skript tun soll (siehe den Abschnitt QubixApp-SDK weiter unten). - Legen Sie im Abschnitt Zeitplan fest, wie oft das Skript automatisch laufen soll (siehe Zeitplan). Sie können ihn leer lassen, wenn Sie es nur manuell ausführen.
- Klicken Sie auf den Button Ausführen unter dem Editor, um das Skript an Live-Daten zu testen — das Ergebnis erscheint in der Konsole (siehe Das Skript testen).
- Schalten Sie den Schalter Aktiv in der oberen rechten Ecke ein und klicken Sie auf Speichern.
Sie können mit dem Tastenkürzel Ctrl + S (unter macOS — Cmd + S) direkt aus dem Editor speichern, ohne den Cursor zum Button zu bewegen.
KI-Assistent
Die linke Spalte ist ein Chat mit dem KI-Assistenten. Beschreiben Sie die Aufgabe in einfachen Worten ("stoppe Anzeigen mit ROAS unter 0,5 und Ausgaben über $20"), und der Assistent generiert fertigen Code gegen das Qubix-SDK. Der Button In Code einfügen unter der Antwort setzt diesen Code direkt in den Editor.
Unter dem Eingabefeld gibt es fertige Beispiel-Prompts — klicken Sie einen davon an, um schnell loszulegen.
Der Assistent kann auch einen Name und eine Beschreibung für das Skript aus seinem Code erfinden — klicken Sie auf das KI-Symbol neben diesen Feldern im Abschnitt Metadaten.
🎬 GIF: eine Anfrage an den KI-Assistenten und das Einfügen des Codes in den Editor
QubixApp-SDK
Ein Skript ist eine Funktion main(), in der Sie über den Befehlssatz QubixApp mit Anzeigendaten arbeiten. Drei Ebenen sind verfügbar:
QubixApp.ads()— Anzeigen,QubixApp.adsets()— Anzeigengruppen,QubixApp.campaigns()— Kampagnen.
Jede von ihnen gibt eine Auswahl zurück, die gefiltert und durchlaufen werden kann. Die Auswahl hat Methoden:
.withCondition('...')— nach einer Bedingung über Metriken auswählen (zum Beispiel'spend_24h > 10 AND roas_24h < 0.5');.orderBy('field', 'desc')— sortieren;.withLimit(n)— die Anzahl begrenzen;.get()— ein Array von Elementen erhalten;.first()— das erste Element erhalten.
Jede Anzeige, Anzeigengruppe oder Kampagne hat Aktionen:
.pause({ duration: '24h', reason: '...' })— für den angegebenen Zeitraum pausieren;.activate({ reason: '...' })— wieder einschalten;.getStatsFor('24h')— Metriken für einen Zeitraum erhalten.
Grundlegendes Beispiel: pausiere Anzeigen mit Ausgaben über $10 und ROAS unter 0,5 über den letzten Tag.
function main() {
const ads = QubixApp.ads()
.withCondition('spend_24h > 10 AND roas_24h < 0.5')
.get()
for (const ad of ads) {
console.log('pausing', ad.name, 'roas24h=', ad.roas_24h)
ad.pause({ duration: '24h', reason: 'low roas' })
}
}
Weitere fertige Snippets finden Sie im Abschnitt Skript-Beispiele.
Die Autovervollständigung funktioniert im Editor: beginnen Sie, ad. oder QubixApp. zu tippen — Qubix schlägt die verfügbaren Felder und Methoden mit Beschreibungen vor. So müssen Sie die Liste der Metriken nicht im Kopf behalten.
Datenbankabfragen
Neben den aktuellen Anzeigen, die über QubixApp verfügbar sind, kann ein Skript Daten direkt aus der Qubix-Datenbank mit dem Befehl sql lesen. Es ist eine schreibgeschützte Abfrage, geschrieben als getaggtes Template:
const rows = sql`
SELECT country, sum(spend) AS spend
FROM hourly_insights
WHERE date >= ${'2026-06-01'}
GROUP BY country`
for (const row of rows) console.log(row.country, row.spend)
Eine Abfrage gibt ein Array von Zeilen zurück; jede Zeile ist ein Objekt, dessen Schlüssel die Spaltennamen sind. Werte, die Sie über ${…} übergeben, werden als sichere Parameter gesendet — Sie escapen nichts von Hand, und SQL-Injection ist nicht möglich. Abfragen sind schreibgeschützt: ein Skript kann Daten lesen, aber nichts ändern. Worauf eine Abfrage zugreifen kann, ist auf die Daten beschränkt, die Ihre Rolle sehen darf.
Zustand zwischen Ausführungen
Ein Skript kann Werte zwischen Ausführungen über ctx.state merken — das ist sein persönlicher Speicher:
ctx.state.set('key', value)— speichern;ctx.state.get('key')— lesen;ctx.state.delete('key')— löschen.
So können Sie zum Beispiel merken, welche Anzeigen bereits verarbeitet wurden, und sie nicht erneut anrühren. Der aktuelle Inhalt des Speichers ist im rechten Panel im Abschnitt Zustand sichtbar — von dort kann ein einzelner Eintrag auch manuell gelöscht werden.
Anfragen an externe Dienste
Der Befehl ctx.fetch(url, opts) stellt eine HTTP-Anfrage nach außen — zum Beispiel, um eine Benachrichtigung an einen Messenger zu senden oder die API eines anderen aufzurufen.
Ausgehende Anfragen sind nur an Adressen aus der Erlaubnisliste zulässig. Der Administrator konfiguriert sie in System → dem Tab JavaScript. Ist die Liste leer, sind ausgehende Anfragen deaktiviert. Beim Versuch, eine Adresse zu erreichen, die nicht auf der Liste steht, zeigt das Skript einen klaren Hinweis in der Konsole.
Zeitplan
Im rechten Panel legt der Abschnitt Zeitplan fest, wann das Skript automatisch läuft. Es kann mehrere Zeitpläne geben — zum Beispiel einmal pro Stunde und zusätzlich zu einer bestimmten Zeit.
- Geben Sie den Zeitplan im Cron-Format ein (zum Beispiel
*/5 * * * *— alle 5 Minuten) und klicken Sie auf +. - Unter der Zeile zeigt Qubix sofort eine Erklärung in einfachen Worten — prüfen Sie, dass Sie einander richtig verstanden haben.
- Um sich die Cron-Syntax nicht merken zu müssen, klicken Sie auf das KI-Symbol in der Zeile und beschreiben Sie den Zeitplan in Worten ("jeden Tag um 9 Uhr") — Qubix füllt den fertigen Ausdruck aus.
Ist kein Zeitplan gesetzt, läuft das Skript nicht von selbst — nur über den Button Ausführen. Damit die automatische Ausführung funktioniert, muss der Schalter Aktiv an sein.
Das Skript mit dem "Ausführen"-Button testen
Unter dem Code-Editor gibt es eine Konsole und einen Button ▶ Ausführen. Er führt den Code, der gerade im Editor steht, an Live-Daten aus — das ist eine sichere Möglichkeit, die Logik zu testen, ohne auf den Zeitplan zu warten. Alles, was das Skript über console.log ausgibt, erscheint in der Konsole zusammen mit der Ausführungszeit, dem Status und der Dauer.
Der Button Ausführen führt echte Aktionen aus. Enthält der Code pause() oder activate(), werden Anzeigen tatsächlich pausiert oder eingeschaltet. Um die Logik ohne Folgen zu testen, kommentieren Sie zuerst die Zeilen mit Aktionen aus und lassen Sie nur console.log stehen.
Der Button Ausführen wird verfügbar, nachdem das Skript zum ersten Mal gespeichert wurde.
Ausführungsverlauf
Der Abschnitt Ausführungen im rechten Panel führt die Historie aller Ausführungen: Zeit, Status (Erfolg, Fehler, Timeout), Dauer und die Anzahl der durchgeführten Aktionen. Ein Klick auf eine Zeile klappt die vollständige Konsolenausgabe dieser Ausführung auf — praktisch, um herauszufinden, warum sich das Skript unerwartet verhalten hat.