स्वचालित नियमों और स्क्रिप्ट का SDK

स्वचालित-पॉज़ नियम और यूज़र-स्क्रिप्ट के कोड के भीतर क्या उपलब्ध है, इसकी संदर्भ-सूची: ad ऑब्जेक्ट के फ़ील्ड, पॉज़ करने और काम पर लौटाने के फ़ंक्शन, और विज्ञापनों को चुनने के सेलेक्टर। विवरण के साथ सभी फ़ील्ड के कैप्शन नियम-संपादक में भी सीधे उपलब्ध हैं — साइड-पैनल «ad.* कुंजियों की संदर्भ-सूची» में (नाम और विवरण से खोज)।

यह Server SDK है — वे कमांड जो Qubix सर्वर पर चलते हैं, न कि Browser SDK जो आगंतुक के ब्राउज़र में चलता है। Server SDK समकालिक है: sql, ctx.fetch, और state सीधे एक मान लौटाते हैं — कोई await या Promises नहीं।

ad ऑब्जेक्ट

स्वचालित-पॉज़ नियम में आपको एक ad ऑब्जेक्ट मिलता है — यह वही विज्ञापन है जिसके लिए जाँच चलाई जा रही है। इसी के माध्यम से आप सभी मेट्रिक्स और एट्रिब्यूट पढ़ते हैं। सभी उपलब्ध फ़ील्ड स्कोप के अनुसार समूहीकृत हैं।

समूह	फ़ील्ड का प्रिफ़िक्स	इसमें क्या है
विज्ञापन	ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status…	स्वयं विज्ञापन की मेट्रिक्स और एट्रिब्यूट
क्रिएटिव	ad.creo_*	क्रिएटिव के अनुसार मेट्रिक्स (इस क्रिएटिव वाले सभी विज्ञापन)
जियो	ad.geo_*	देश के अनुसार मेट्रिक्स
ऑफ़र	ad.offer_*	ऑफ़र की मेट्रिक्स और पैरामीटर (पेआउट, कैप)
नेटवर्क	ad.network_*	नेटवर्क के अनुसार मेट्रिक्स
पिछली अवधि	ad.prev_*	पिछली अवधि के लिए वही मेट्रिक्स (तुलना हेतु)

मेट्रिक्स की पूरी सूची, समय-अंतराल (_1h…_total) और हर प्रिफ़िक्स का अर्थ — मेट्रिक्स और कॉलम सेक्शन में।

सावधानी

किसी अस्तित्वहीन फ़ील्ड (ad.something_wrong) तक पहुँचने पर नियम तुरंत एक त्रुटि के साथ रुक जाता है। नामों को संपादक की संदर्भ-सूची से मिलाकर जाँचें।

पॉज़

तीन फ़ंक्शन — स्कोप के अनुसार। विज्ञापन, AdSet और कैंपेन।

फ़ंक्शन	कार्रवाई
pauseAd(duration, reason?)	वर्तमान विज्ञापन को पॉज़ करें
pauseAdset({ adsetId, duration, reason? })	AdSet को पॉज़ करें
pauseCampaign({ campaignId, duration, reason? })	कैंपेन को पॉज़ करें

pauseAd के लिए अवधि को एक स्ट्रिंग के रूप में पास करना ही पर्याप्त है; AdSet और कैंपेन के लिए स्पष्ट adsetId / campaignId के साथ ऑब्जेक्ट-रूप आवश्यक है।

अवधियाँ (duration):

मान	अर्थ
6h / 12h / 24h	N घंटों के लिए पॉज़
next_day_target_geo	लक्षित देश के समय में अगले दिन की शुरुआत तक
next_day_ad_account	विज्ञापन-अकाउंट के समय में अगले दिन की शुरुआत तक
permanent	स्थायी पॉज़
while_matches	जब तक नियम की शर्त पूरी होती रहे

reason एक वैकल्पिक टिप्पणी है जो लॉग में जाती है। यदि इसे छोड़ दिया जाए, तो नियम का नाम प्रतिस्थापित कर दिया जाता है।

काम पर लौटाना

फ़ंक्शन	कार्रवाई
activateAd(reason?)	वर्तमान विज्ञापन को काम पर लौटाएँ
activateAdset({ adsetId, reason? })	AdSet को काम पर लौटाएँ
activateCampaign({ campaignId, reason? })	कैंपेन को काम पर लौटाएँ

पड़ोसी विज्ञापन

किसी नियम के भीतर आप उसी AdSet या कैंपेन के अन्य विज्ञापनों को देख सकते हैं — उदाहरण के लिए, यदि केवल एक विज्ञापन गिरा हो तो पूरे AdSet को रोकने के लिए।

फ़ंक्शन	लौटाता है
getAd(id)	ad_id के अनुसार एक विज्ञापन
getAdset()	वर्तमान विज्ञापन के AdSet के सभी विज्ञापन
getCampaign()	वर्तमान विज्ञापन के कैंपेन के सभी विज्ञापन

डीबग आउटपुट के लिए console.log / console.warn / console.error और skipNextRules() — इस विज्ञापन के लिए शेष नियमों को छोड़ देना — भी उपलब्ध हैं।

QubixApp सेलेक्टर (स्क्रिप्ट के लिए)

यूज़र-स्क्रिप्ट में QubixApp ऑब्जेक्ट उपलब्ध है — यह शर्तों के अनुसार विज्ञापनों, AdSet और कैंपेन को चुनता है। हर चुने गए तत्व के अपने आँकड़े और पॉज़-मेथड होते हैं।

मेथड	किसका चयन लौटाता है
QubixApp.ads()	विज्ञापन
QubixApp.adsets()	AdSet
QubixApp.campaigns()	कैंपेन

चयन के मेथड (श्रृंखलाबद्ध):

मेथड	यह क्या करता है
.withCondition(sql)	किसी शर्त के अनुसार फ़िल्टर करें
.filter(fn)	किसी फ़ंक्शन से फ़िल्टर करें
.orderBy(field, dir)	क्रमबद्ध करें ('asc' / 'desc')
.withLimit(n)	तत्वों की संख्या सीमित करें
.get()	तत्वों की एक सरणी प्राप्त करें
.first()	पहला तत्व प्राप्त करें

तत्व के मेथड:

मेथड	कार्रवाई
.pause({ duration, reason? })	पॉज़ करें
.activate({ reason? })	काम पर लौटाएँ
.getStatsFor(period)	किसी अंतराल के लिए मेट्रिक्स ('1h'…'total')
.getAds()	AdSet / कैंपेन के भीतर के विज्ञापन
.getAdsets()	कैंपेन के भीतर के AdSet

getStatsFor चुने गए अंतराल के लिए मेट्रिक्स का एक सेट लौटाता है: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i।

स्क्रिप्ट का कॉन्टेक्स्ट

स्क्रिप्ट में अतिरिक्त रूप से ctx ऑब्जेक्ट उपलब्ध है।

फ़ील्ड / मेथड	उद्देश्य
ctx.state.get/set/delete/keys	रन के बीच स्टेट को संरक्षित रखना
ctx.fetch(url, opts?)	एक HTTP अनुरोध (होस्ट अनुमति-सूची में होना चाहिए, देखें सेटिंग्स में JavaScript)
ctx.now()	वर्तमान समय
ctx.script	वर्तमान स्क्रिप्ट की जानकारी

सावधानी

ctx ऑब्जेक्ट (ctx.fetch सहित) केवल स्क्रिप्ट में मौजूद है — यह स्वचालित-पॉज़ नियमों के भीतर उपलब्ध नहीं है। और स्क्रिप्ट में भी ctx.fetch केवल सर्वर पर एक वास्तविक रन में ही काम करता है: ब्राउज़र में टेस्ट-रन के दौरान नेटवर्क कॉल अक्षम रहते हैं, इसलिए वास्तविक रन के माध्यम से सत्यापित करें।

साझा स्टेट

निजी ctx.state के अलावा, एक साझा स्टोर ctx.state.global भी है, जो एक साथ हर स्क्रिप्ट, नियम और साइट हैंडलर को दिखती है।

मेथड	कार्रवाई
ctx.state.global.get(key)	एक मान पढ़ें
ctx.state.global.keys()	चाबियों की सूची लें
ctx.state.global.set(key, value)	एक मान लिखें
ctx.state.global.delete(key)	एक मान मिटाएँ

कोई भी स्क्रिप्ट या नियम साझा स्टोर पढ़ सकता है। लिखना (set / delete) केवल एडमिनिस्ट्रेटर के स्वामित्व वाली स्क्रिप्ट या नियम से अनुमत है — अन्यथा लिखने पर त्रुटि आती है। साझा लुकअप के लिए उपयोगी: एडमिनिस्ट्रेटर एक बार मान लिखता है, बाकी सब उसे पढ़ते हैं।

सीमाएँ

• ctx.fetch: डिफ़ॉल्ट रूप से 10 सेकंड का टाइमआउट (अधिकतम 30), 1 MB तक की प्रतिक्रिया, प्रति रन अधिकतम 20 अनुरोध।
• sql: एक क्वेरी अधिकतम कुछ हजार पंक्तियाँ लौटाती है — एडमिनिस्ट्रेटर सेटिंग्स में सटीक सीमा निर्धारित करता है। बड़े चुनाव के लिए, क्वेरी में ही एग्रीगेट करें।

सटीक सीमा मान सिस्टम → JavaScript टैब में कॉन्फ़िगर किए जाते हैं।

केवल-पठन वाला sql

टैग्ड टेम्पलेट sql\SELECT …` मालिक की अनुमतियों के भीतर एक केवल-पठन डेटा-क्वेरी चलाता है। यह **स्वचालित-पॉज़ नियमों (Britva) और यूज़र-स्क्रिप्ट दोनों में** उपलब्ध है — बशर्ते संबंधित सिस्टम-सेटिंग सक्षम हो। ब्राउज़र में टेस्ट-रन के दौरान यह अक्षम रहता है (ctx.fetchकी तरह), इसलिएsql` का उपयोग करने वाले नियम या स्क्रिप्ट को सर्वर पर वास्तविक रन के माध्यम से सत्यापित करें।

जिन टेबल और कॉलम तक क्वेरी पहुँच सकती है उनकी पूरी सूची sql क्वेरी के लिए टेबल में है।

आगे क्या

मेट्रिक्स और कॉलम

`ad.*` फ़ील्ड की पूरी सूची।

स्वचालित नियम (Britva)

नियम कैसे बनाएँ और टेस्ट करें।

स्क्रिप्ट

यूज़र बैकग्राउंड स्क्रिप्ट।

एक्शन

व्यवहार में पॉज़ और वापसी के फ़ंक्शन।