Pisanie skryptu
Edytor skryptów to przestrzeń robocza, w której pisze się kod, testuje go na danych na żywo i konfiguruje harmonogram. Ekran jest podzielony na trzy części: po lewej — asystent AI, na środku — edytor kodu i konsola, po prawej — panel ustawień (metadane, harmonogram, stan, historia uruchomień).
Jak utworzyć skrypt
- Proszę otworzyć sekcję Skrypty i kliknąć + Utwórz script. Otworzy się edytor z szablonem kodu.
- W panelu po prawej, w sekcji Metadane, proszę wypełnić Nazwa i Opis skryptu.
- W centralnym edytorze proszę napisać treść funkcji
main()— dokładnie to, co skrypt ma robić (patrz sekcja SDK QubixApp poniżej). - W sekcji Harmonogram proszę ustawić, jak często skrypt będzie uruchamiał się automatycznie (patrz Harmonogram). Można zostawić puste, jeśli będzie uruchamiany wyłącznie ręcznie.
- Proszę kliknąć przycisk Uruchom pod edytorem, aby przetestować skrypt na danych na żywo — wynik pojawi się w konsoli (patrz Testowanie skryptu).
- Proszę włączyć przełącznik Aktywny w prawym górnym rogu i kliknąć Zapisz.
Można zapisać skrótem klawiszowym Ctrl + S (na macOS — Cmd + S) bezpośrednio z edytora, bez przenoszenia kursora na przycisk.
Asystent AI
Lewa kolumna to czat z asystentem AI. Proszę opisać zadanie zwykłymi słowami ("zatrzymaj reklamy z ROAS poniżej 0,5 i wydatkiem powyżej 20 $"), a asystent wygeneruje gotowy kod dla Qubix SDK. Przycisk Wstaw do Code pod odpowiedzią umieszcza ten kod od razu w edytorze.
Poniżej pola wprowadzania znajdują się gotowe przykładowe podpowiedzi — proszę kliknąć dowolną z nich, aby szybko zacząć.
Asystent może też wymyślić Nazwa i Opis dla skryptu na podstawie jego kodu — proszę kliknąć ikonę AI obok tych pól w sekcji Metadane.
🎬 GIF: zapytanie do asystenta AI i wstawienie kodu do edytora
SDK QubixApp
Skrypt to funkcja main(), wewnątrz której pracuje się z danymi reklam za pomocą zestawu poleceń QubixApp. Dostępne są trzy poziomy:
QubixApp.ads()— reklamy,QubixApp.adsets()— zestawy reklam,QubixApp.campaigns()— kampanie.
Każdy z nich zwraca wybór, który można filtrować i po którym można iterować. Wybór ma metody:
.withCondition('...')— wybierz według warunku na metrykach (na przykład'spend_24h > 10 AND roas_24h < 0.5');.orderBy('field', 'desc')— sortuj;.withLimit(n)— ogranicz liczbę;.get()— pobierz tablicę elementów;.first()— pobierz pierwszy element.
Każda reklama, zestaw reklam lub kampania ma akcje:
.pause({ duration: '24h', reason: '...' })— wstrzymaj na określony okres;.activate({ reason: '...' })— włącz ponownie;.getStatsFor('24h')— pobierz metryki za okres.
Podstawowy przykład: wstrzymaj reklamy z wydatkiem powyżej 10 $ i ROAS poniżej 0,5 w ciągu ostatniej doby.
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' })
}
}
Więcej gotowych fragmentów znajduje się w sekcji Przykłady skryptów.
W edytorze działa autouzupełnianie: proszę zacząć wpisywać ad. lub QubixApp. — Qubix podpowie dostępne pola i metody wraz z opisami. Dzięki temu nie trzeba trzymać listy metryk w głowie.
Zapytania do bazy danych
Oprócz bieżących reklam dostępnych przez QubixApp, skrypt może odczytywać dane prosto z bazy danych Qubix za pomocą polecenia sql. Jest to zapytanie tylko do odczytu, zapisane jako tagged 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)
Zapytanie zwraca tablicę wierszy; każdy wiersz to obiekt, którego klucze są nazwami kolumn. Wartości przekazywane przez ${…} są wysyłane jako bezpieczne parametry — nie trzeba niczego ręcznie escape'ować, a SQL injection jest niemożliwy. Zapytania są tylko do odczytu: skrypt może odczytywać dane, ale nie może niczego zmieniać. Zakres dostępny dla zapytania jest ograniczony do danych, które wolno widzieć Pana/Pani roli.
Stan pomiędzy uruchomieniami
Skrypt może zapamiętywać wartości pomiędzy uruchomieniami poprzez ctx.state — to jego osobista pamięć:
ctx.state.set('key', value)— zapisz;ctx.state.get('key')— odczytaj;ctx.state.delete('key')— usuń.
Na przykład pozwala to zapamiętać, które reklamy zostały już przetworzone, i nie ruszać ich ponownie. Bieżąca zawartość pamięci jest widoczna w panelu po prawej w sekcji Stan — stamtąd można też ręcznie usunąć pojedynczy wpis.
Żądania do usług zewnętrznych
Polecenie ctx.fetch(url, opts) wykonuje żądanie HTTP na zewnątrz — na przykład aby wysłać powiadomienie do komunikatora lub wywołać cudze API.
Żądania wychodzące są dozwolone tylko do adresów z listy dozwolonych. Konfiguruje ją administrator w System → karta JavaScript. Jeśli lista jest pusta, żądania wychodzące są wyłączone. Przy próbie sięgnięcia do adresu, którego nie ma na liście, skrypt wyświetli w konsoli czytelną podpowiedź.
Harmonogram
W panelu po prawej sekcja Harmonogram ustawia, kiedy skrypt uruchamia się automatycznie. Harmonogramów może być kilka — na przykład raz na godzinę i dodatkowo o określonej porze.
- Proszę wpisać harmonogram w formacie cron (na przykład
*/5 * * * *— co 5 minut) i kliknąć +. - Pod wierszem Qubix od razu pokazuje wyjaśnienie zwykłymi słowami — proszę sprawdzić, czy dobrze się Państwo zrozumieli.
- Aby nie przypominać sobie składni cron, proszę kliknąć ikonę AI w wierszu i opisać harmonogram słowami ("codziennie o 9 rano") — Qubix uzupełni gotowe wyrażenie.
Jeśli harmonogram nie jest ustawiony, skrypt nie uruchomi się samodzielnie — tylko przez przycisk Uruchom. Aby automatyczne uruchamianie działało, przełącznik Aktywny musi być włączony.
Testowanie skryptu przyciskiem „Uruchom”
Pod edytorem kodu znajduje się konsola i przycisk ▶ Uruchom. Wykonuje on kod aktualnie znajdujący się w edytorze na danych na żywo — to bezpieczny sposób na przetestowanie logiki bez czekania na harmonogram. Wszystko, co skrypt wypisze przez console.log, pojawia się w konsoli wraz z czasem uruchomienia, statusem i czasem trwania.
Przycisk Uruchom wykonuje rzeczywiste działania. Jeśli kod zawiera pause() lub activate(), reklamy zostaną faktycznie wstrzymane lub włączone. Aby przetestować logikę bez konsekwencji, proszę najpierw zakomentować wiersze z działaniami i pozostawić tylko console.log.
Przycisk Uruchom staje się dostępny po pierwszym zapisaniu skryptu.
Historia uruchomień
Sekcja Uruchomienia w panelu po prawej przechowuje historię wszystkich wykonań: czas, status (sukces, błąd, timeout), czas trwania oraz liczbę wykonanych działań. Kliknięcie wiersza rozwija pełne wyjście konsoli z tego uruchomienia — przydatne do ustalenia, dlaczego skrypt zachował się niespodziewanie.