Bir betik yazmak
Betik düzenleyici, kod yazdığınız, onu canlı veriler üzerinde test ettiğiniz ve zamanlamayı ayarladığınız çalışma alanıdır. Ekran üç bölüme ayrılmıştır: solda — AI asistanı, ortada — kod düzenleyici ve konsol, sağda — ayarlar paneli (üst veriler, zamanlama, durum, çalıştırma geçmişi).
Bir betik nasıl oluşturulur
- Scriptler bölümünü açın ve + Script oluştur öğesine tıklayın. Düzenleyici, bir kod şablonuyla açılır.
- Sağ panelde, Meta veriler bölümünde betiğin Ad ve Açıklama alanlarını doldurun.
- Merkezi düzenleyicide,
main()fonksiyonunun gövdesini yazın — betiğin tam olarak ne yapması gerektiğini (aşağıdaki QubixApp SDK bölümüne bakın). - Zamanlama bölümünde, betiğin otomatik olarak ne sıklıkta çalışacağını ayarlayın (Zamanlama bölümüne bakın). Yalnızca manuel olarak çalıştıracaksanız boş bırakabilirsiniz.
- Betiği canlı veriler üzerinde test etmek için düzenleyicinin altındaki Run düğmesine tıklayın — sonuç konsolda görünür (Betiği test etmek bölümüne bakın).
- Sağ üst köşedeki Aktif anahtarını açın ve Kaydet öğesine tıklayın.
İmleci düğmeye taşımadan, doğrudan düzenleyiciden Ctrl + S klavye kısayoluyla (macOS'ta — Cmd + S) kaydedebilirsiniz.
AI asistanı
Sol sütun, AI asistanıyla bir sohbettir. Görevi sade kelimelerle anlatın ("ROAS'ı 0,5'in altında ve harcaması 20 doların üzerinde olan reklamları durdur") ve asistan, Qubix SDK'ya karşı hazır kod üretsin. Yanıtın altındaki Code'a ekle düğmesi bu kodu doğrudan düzenleyiciye yerleştirir.
Giriş alanının altında hazır örnek istemler bulunur — hızlıca başlamak için herhangi birine tıklayın.
Asistan, betiğin kodundan onun için bir Ad ve Açıklama da önerebilir — Meta veriler bölümündeki bu alanların yanındaki AI simgesine tıklayın.
🎬 GIF: AI asistanına bir istek ve kodun düzenleyiciye eklenmesi
QubixApp SDK
Bir betik, içinde QubixApp komut kümesi aracılığıyla reklam verileriyle çalıştığınız bir main() fonksiyonudur. Üç düzey kullanılabilir:
QubixApp.ads()— reklamlar,QubixApp.adsets()— reklam setleri,QubixApp.campaigns()— kampanyalar.
Bunların her biri, filtrelenebilen ve üzerinde yinelenebilen bir seçim döndürür. Seçimin metotları vardır:
.withCondition('...')— metriklere ilişkin bir koşula göre seçim (örneğin,'spend_24h > 10 AND roas_24h < 0.5');.orderBy('field', 'desc')— sıralama;.withLimit(n)— sayıyı sınırlama;.get()— öğelerden oluşan bir dizi alma;.first()— ilk öğeyi alma.
Her reklamın, reklam setinin veya kampanyanın eylemleri vardır:
.pause({ duration: '24h', reason: '...' })— belirtilen süre boyunca duraklatma;.activate({ reason: '...' })— yeniden açma;.getStatsFor('24h')— bir dönem için metrikleri alma.
Temel örnek: geçen gün içinde harcaması 10 doların üzerinde ve ROAS'ı 0,5'in altında olan reklamları duraklatma.
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' })
}
}
Daha fazla hazır kod parçası Betik örnekleri bölümündedir.
Düzenleyicide otomatik tamamlama çalışır: ad. veya QubixApp. yazmaya başlayın — Qubix, kullanılabilir alanları ve metotları açıklamalarıyla önerecektir. Bu sayede metrik listesini aklınızda tutmak zorunda kalmazsınız.
Veritabanı sorguları
QubixApp aracılığıyla kullanılabilen mevcut reklamların yanı sıra, bir betik sql komutuyla doğrudan Qubix veritabanından veri okuyabilir. Bu, etiketli bir şablon olarak yazılan salt okunur bir sorgudur:
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)
Bir sorgu, satırlardan oluşan bir dizi döndürür; her satır, anahtarları sütun adları olan bir nesnedir. ${…} aracılığıyla geçirdiğiniz değerler güvenli parametreler olarak gönderilir — hiçbir şeyi elle kaçış karakterine almazsınız ve SQL injection mümkün değildir. Sorgular salt okunurdur: bir betik veri okuyabilir ancak hiçbir şeyi değiştiremez. Bir sorgunun erişebileceği şey, rolünüzün görmesine izin verilen verilerle sınırlıdır.
Çalıştırmalar arasında durum
Bir betik, ctx.state aracılığıyla çalıştırmalar arasında değerleri hatırlayabilir — bu, onun kişisel belleğidir:
ctx.state.set('key', value)— kaydetme;ctx.state.get('key')— okuma;ctx.state.delete('key')— silme.
Örneğin bu, hangi reklamların zaten işlendiğini hatırlamanıza ve onlara tekrar dokunmamanıza olanak tanır. Belleğin güncel içeriği, sağ panelde Durum bölümünde görünür — oradan tekil bir kayıt manuel olarak da silinebilir.
Dış hizmetlere istekler
ctx.fetch(url, opts) komutu, dışarıya bir HTTP isteği yapar — örneğin, bir mesajlaşma uygulamasına bildirim göndermek veya başka birinin API'sini çağırmak için.
Giden istekler yalnızca izin listesindeki adreslere izin verilir. Yönetici bunu Sistem → JavaScript sekmesinde yapılandırır. Liste boşsa, giden istekler devre dışıdır. Listede olmayan bir adrese ulaşmaya çalışırken, betik konsolda anlaşılır bir ipucu gösterir.
Zamanlama
Sağ panelde, Zamanlama bölümü betiğin ne zaman otomatik olarak çalışacağını ayarlar. Birkaç zamanlama olabilir — örneğin, saatte bir kez ve ek olarak belirli bir saatte.
- Zamanlamayı cron biçiminde girin (örneğin,
*/5 * * * *— her 5 dakikada bir) ve + öğesine tıklayın. - Satırın altında Qubix, hemen sade kelimelerle bir açıklama gösterir — birbirinizi doğru anladığınızı kontrol edin.
- Cron sözdizimini hatırlamamak için satırdaki AI simgesine tıklayın ve zamanlamayı kelimelerle anlatın ("her gün sabah 9'da") — Qubix, hazır ifadeyi dolduracaktır.
Hiçbir zamanlama ayarlanmamışsa, betik kendi kendine çalışmaz — yalnızca Run düğmesi aracılığıyla. Otomatik çalıştırmanın işlemesi için Aktif anahtarının açık olması gerekir.
Betiği "Run" düğmesiyle test etmek
Kod düzenleyicinin altında bir konsol ve bir ▶ Run düğmesi bulunur. Bu, şu anda düzenleyicide olan kodu canlı veriler üzerinde çalıştırır — bu, zamanlamayı beklemeden mantığı test etmenin güvenli bir yoludur. Betiğin console.log aracılığıyla çıktıladığı her şey, çalıştırma süresi, durumu ve süresiyle birlikte konsolda görünür.
Run düğmesi gerçek eylemler gerçekleştirir. Kod pause() veya activate() içeriyorsa, reklamlar gerçekten duraklatılır veya açılır. Mantığı sonuçsuz test etmek için, önce eylem içeren satırları yorum satırı haline getirin ve yalnızca console.log bırakın.
Run düğmesi, betik ilk kez kaydedildikten sonra kullanılabilir hale gelir.
Çalıştırma geçmişi
Sağ paneldeki Çalıştırmalar bölümü, tüm yürütmelerin geçmişini tutar: zaman, durum (başarı, hata, zaman aşımı), süre ve gerçekleştirilen eylemlerin sayısı. Bir satıra tıklamak, o çalıştırmanın tam konsol çıktısını genişletir — betiğin neden beklenmedik şekilde davrandığını anlamak için kullanışlıdır.