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_* | เมตริกตามครีเอทีฟ (โฆษณาทุกตัวที่ใช้ครีเอทีฟนี้) |
| Geo | ad.geo_* | เมตริกตามประเทศ |
| ออฟเฟอร์ | ad.offer_* | เมตริกและพารามิเตอร์ของออฟเฟอร์ (payout, cap) |
| เน็ตเวิร์ก | 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 ซึ่งมองเห็นได้จากทุกสคริปต์ ทุกกฎ และทุก site handler พร้อมกัน
| เมธอด | การกระทำ |
|---|---|
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