Otomatik kural ve betik SDK'sı
Bir otomatik duraklatma kuralının ve kullanıcı betiğinin kodu içinde nelerin kullanılabilir olduğuna dair bir referans: ad nesnesinin alanları, duraklatma ve devam ettirme fonksiyonları ve reklam seçmeye yarayan seçiciler. Açıklamalarıyla birlikte tüm alanların başlıkları, doğrudan kural düzenleyicide de mevcuttur — ad.* anahtar referansı yan panelinde (ada ve açıklamaya göre arama).
Bu, ziyaretçinin tarayıcısında çalışan Browser SDK'nın aksine Qubix sunucusunda çalışan Server SDK'dır. Server SDK eş zamanlıdır: sql, ctx.fetch ve durum değerini doğrudan döndürür — await veya Promise kullanımı gerekmez.
ad nesnesi
Bir otomatik duraklatma kuralında tek bir ad nesnesi alırsınız — bu, kontrolün çalıştırıldığı reklamdır. Bunun üzerinden tüm metrikleri ve nitelikleri okursunuz. Kullanılabilir tüm alanlar kapsama göre gruplanmıştır.
| Grup | Alan öneki | İçeriği |
|---|---|---|
| Reklam | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Reklamın kendisinin metrikleri ve nitelikleri |
| Yaratıcı | ad.creo_* | Yaratıcıya göre metrikler (bu yaratıcıya sahip tüm reklamlar) |
| Coğrafya | ad.geo_* | Ülkeye göre metrikler |
| Teklif | ad.offer_* | Teklifin metrikleri ve parametreleri (ödeme, üst sınır) |
| Ağ | ad.network_* | Ağa göre metrikler |
| Önceki dönem | ad.prev_* | Önceki dönem için aynı metrikler (karşılaştırma amacıyla) |
Metriklerin tam listesi, zaman pencereleri (_1h…_total) ve her bir önekin anlamı — Metrikler ve sütunlar bölümünde.
Var olmayan bir alana erişmek (ad.something_wrong) kuralı hemen bir hatayla durdurur. Adları düzenleyicideki referansa göre kontrol edin.
Duraklatma
Üç fonksiyon — kapsama göre. Reklam, reklam grubu ve kampanya.
| Fonksiyon | Eylem |
|---|---|
pauseAd(duration, reason?) | Geçerli reklamı duraklat |
pauseAdset({ adsetId, duration, reason? }) | Reklam grubunu duraklat |
pauseCampaign({ campaignId, duration, reason? }) | Kampanyayı duraklat |
pauseAd için süreyi bir dize olarak geçirmek yeterlidir; reklam grubu ve kampanya için açık bir adsetId / campaignId içeren nesne biçimi gereklidir.
Süreler (duration):
| Değer | Anlamı |
|---|---|
6h / 12h / 24h | N saat duraklat |
next_day_target_geo | Hedef ülkenin saatine göre ertesi günün başlangıcına kadar |
next_day_ad_account | Reklam hesabının saatine göre ertesi günün başlangıcına kadar |
permanent | Kalıcı bir duraklatma |
while_matches | Kural koşulu geçerli olduğu sürece |
reason, günlüğe işlenen isteğe bağlı bir yorumdur. Atlanırsa, kural adı yerine konur.
Devam ettirme
| Fonksiyon | Eylem |
|---|---|
activateAd(reason?) | Geçerli reklamı devam ettir |
activateAdset({ adsetId, reason? }) | Reklam grubunu devam ettir |
activateCampaign({ campaignId, reason? }) | Kampanyayı devam ettir |
Komşu reklamlar
Bir kural içinde, aynı reklam grubundaki veya kampanyadaki diğer reklamlara bakabilirsiniz — örneğin, yalnızca bir reklam düştüyse tüm reklam grubunu durdurmak için.
| Fonksiyon | Döndürdüğü |
|---|---|
getAd(id) | ad_id değerine göre bir reklam |
getAdset() | Geçerli reklamın reklam grubundaki tüm reklamlar |
getCampaign() | Geçerli reklamın kampanyasındaki tüm reklamlar |
Ayrıca hata ayıklama çıktısı için console.log / console.warn / console.error ve bu reklam için kalan kuralları atlayan skipNextRules() da kullanılabilir.
QubixApp seçicileri (betikler için)
Kullanıcı betiklerinde QubixApp nesnesi kullanılabilir — reklamları, reklam gruplarını ve kampanyaları koşullara göre seçer. Seçilen her öğenin kendi istatistikleri ve duraklatma yöntemleri vardır.
| Yöntem | Döndürdüğü seçim |
|---|---|
QubixApp.ads() | Reklamlar |
QubixApp.adsets() | Reklam grupları |
QubixApp.campaigns() | Kampanyalar |
Seçim yöntemleri (zincirlenir):
| Yöntem | İşlevi |
|---|---|
.withCondition(sql) | Bir koşula göre filtrele |
.filter(fn) | Bir fonksiyonla filtrele |
.orderBy(field, dir) | Sırala ('asc' / 'desc') |
.withLimit(n) | Öğe sayısını sınırla |
.get() | Bir öğe dizisi al |
.first() | İlk öğeyi al |
Öğe yöntemleri:
| Yöntem | Eylem |
|---|---|
.pause({ duration, reason? }) | Duraklat |
.activate({ reason? }) | Devam ettir |
.getStatsFor(period) | Bir pencere için metrikler ('1h'…'total') |
.getAds() | Bir reklam grubu / kampanya içindeki reklamlar |
.getAdsets() | Bir kampanya içindeki reklam grupları |
getStatsFor, seçilen pencere için bir metrik kümesi döndürür: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Betik bağlamı
Betiklerde ek olarak ctx nesnesi kullanılabilir.
| Alan / yöntem | Amacı |
|---|---|
ctx.state.get/set/delete/keys | Çalıştırmalar arasında durumu kalıcı hale getirme |
ctx.fetch(url, opts?) | Bir HTTP isteği (ana bilgisayar izin listesinde olmalıdır, bkz. Ayarlardaki JavaScript) |
ctx.now() | Geçerli zaman |
ctx.script | Geçerli betik hakkında bilgi |
ctx nesnesi (ctx.fetch dahil) yalnızca betiklerde bulunur — otomatik duraklatma kuralları içinde kullanılamaz. Ve betiklerde bile ctx.fetch yalnızca sunucudaki gerçek bir çalıştırmada işler: tarayıcıdaki test çalıştırmasında ağ çağrıları devre dışıdır, bu nedenle gerçek bir çalıştırmayla doğrulayın.
Paylaşılan durum
Özel ctx.state'in yanı sıra, her betik, kural ve site işleyicisi tarafından aynı anda erişilebilen ctx.state.global adlı paylaşılan bir depo mevcuttur.
| Yöntem | Eylem |
|---|---|
ctx.state.global.get(key) | Bir değeri oku |
ctx.state.global.keys() | Anahtarları listele |
ctx.state.global.set(key, value) | Bir değer yaz |
ctx.state.global.delete(key) | Bir değeri sil |
Herhangi bir betik veya kural paylaşılan depoyu okuyabilir. Yazma işlemi (set / delete) yalnızca bir yöneticiye ait betik veya kuraldan gerçekleştirilebilir — aksi takdirde yazma işlemi hata fırlatır. Yöneticinin bir değeri bir kez yazdığı ve diğer herkesin okuduğu paylaşılan aramalar için kullanışlıdır.
ctx.fetch: varsayılan olarak 10 saniyelik zaman aşımı (en fazla 30), en fazla 1 MB yanıt, çalıştırma başına en fazla 20 istek.sql: tek bir sorgu en fazla birkaç bin satır döndürür — yönetici bu sınırı ayarlardan belirler. Büyük seçimler için doğrudan sorguda toplu işlem yapın.
Sınır değerleri Sistem → JavaScript sekmesinde yapılandırılır.
Salt okunur sql
Etiketli şablon sql\SELECT …`, sahibinin izinleri dahilinde salt okunur bir veri sorgusu çalıştırır. Hem otomatik duraklatma kurallarında (Britva) hem de kullanıcı betiklerinde kullanılabilir — ilgili sistem ayarının etkinleştirilmiş olması koşuluyla. Tarayıcıdaki test çalıştırmasında devre dışıdır (ctx.fetchgibi), bu nedenlesql` kullanan bir kuralı veya betiği sunucudaki gerçek bir çalıştırmayla doğrulayın.
Bir sorgunun erişebildiği tabloların ve sütunların tam listesi sql sorguları için tablolar bölümündedir.