SDK cho quy tắc tự động và script
Tài liệu tham khảo về những gì có sẵn bên trong mã của một quy tắc tự động tạm dừng và một script người dùng: các trường của đối tượng ad, các hàm để tạm dừng và khôi phục, cùng các bộ chọn để chọn quảng cáo. Phần chú thích cho tất cả các trường kèm mô tả cũng có sẵn ngay trong trình soạn thảo quy tắc — ở bảng bên Tham chiếu khóa ad.* (tìm kiếm theo tên và mô tả).
Đây là Server SDK — các lệnh chạy trên máy chủ Qubix, khác với Browser SDK chạy trong trình duyệt của khách truy cập. Server SDK hoạt động đồng bộ: sql, ctx.fetch và state trả về giá trị trực tiếp — không cần await hay Promise.
Đối tượng ad
Trong một quy tắc tự động tạm dừng, bạn nhận được một đối tượng ad duy nhất — đây là quảng cáo mà việc kiểm tra đang được chạy cho nó. Thông qua đối tượng này bạn đọc tất cả các chỉ số và thuộc tính. Tất cả các trường có sẵn được nhóm theo phạm vi.
| Nhóm | Tiền tố trường | Bên trong là gì |
|---|---|---|
| Quảng cáo | ad.spend_24h, ad.roas_24h, ad.primary_country, ad.effective_status… | Các chỉ số và thuộc tính của chính quảng cáo |
| Creative | ad.creo_* | Các chỉ số theo creative (tất cả quảng cáo dùng creative này) |
| Geo | ad.geo_* | Các chỉ số theo quốc gia |
| Offer | ad.offer_* | Các chỉ số và tham số của offer (payout, cap) |
| Network | ad.network_* | Các chỉ số theo network |
| Kỳ trước | ad.prev_* | Cùng các chỉ số đó cho kỳ trước (để so sánh) |
Danh sách đầy đủ các chỉ số, các khung thời gian (_1h…_total), và ý nghĩa của từng tiền tố — xem trong mục Chỉ số và cột.
Truy cập một trường không tồn tại (ad.something_wrong) sẽ lập tức hủy bỏ quy tắc kèm lỗi. Hãy đối chiếu tên với phần tham khảo trong trình soạn thảo.
Tạm dừng
Ba hàm — theo phạm vi. Quảng cáo, nhóm quảng cáo, và chiến dịch.
| Hàm | Hành động |
|---|---|
pauseAd(duration, reason?) | Tạm dừng quảng cáo hiện tại |
pauseAdset({ adsetId, duration, reason? }) | Tạm dừng nhóm quảng cáo |
pauseCampaign({ campaignId, duration, reason? }) | Tạm dừng chiến dịch |
Với pauseAd chỉ cần truyền thời lượng dưới dạng chuỗi; với nhóm quảng cáo và chiến dịch thì bắt buộc dùng dạng đối tượng có adsetId / campaignId rõ ràng.
Thời lượng (duration):
| Giá trị | Ý nghĩa |
|---|---|
6h / 12h / 24h | Tạm dừng trong N giờ |
next_day_target_geo | Cho đến khi bắt đầu ngày kế tiếp theo giờ của quốc gia mục tiêu |
next_day_ad_account | Cho đến khi bắt đầu ngày kế tiếp theo giờ của tài khoản quảng cáo |
permanent | Tạm dừng vĩnh viễn |
while_matches | Trong khi điều kiện của quy tắc còn đúng |
reason là một bình luận tùy chọn được ghi vào nhật ký. Nếu bỏ qua, tên quy tắc sẽ được thay vào.
Khôi phục
| Hàm | Hành động |
|---|---|
activateAd(reason?) | Khôi phục quảng cáo hiện tại |
activateAdset({ adsetId, reason? }) | Khôi phục nhóm quảng cáo |
activateCampaign({ campaignId, reason? }) | Khôi phục chiến dịch |
Các quảng cáo lân cận
Bên trong một quy tắc, bạn có thể xem các quảng cáo khác trong cùng nhóm quảng cáo hoặc chiến dịch — ví dụ, để dừng toàn bộ nhóm quảng cáo nếu chỉ một quảng cáo bị sụt giảm.
| Hàm | Trả về |
|---|---|
getAd(id) | Một quảng cáo theo ad_id của nó |
getAdset() | Tất cả quảng cáo trong nhóm quảng cáo của quảng cáo hiện tại |
getCampaign() | Tất cả quảng cáo trong chiến dịch của quảng cáo hiện tại |
Ngoài ra còn có console.log / console.warn / console.error để xuất thông tin gỡ lỗi và skipNextRules() — bỏ qua các quy tắc còn lại cho quảng cáo này.
Các bộ chọn QubixApp (cho script)
Trong các script người dùng, đối tượng QubixApp có sẵn — nó chọn quảng cáo, nhóm quảng cáo và chiến dịch theo điều kiện. Mỗi phần tử được chọn có thống kê và các phương thức tạm dừng riêng.
| Phương thức | Trả về một tập chọn gồm |
|---|---|
QubixApp.ads() | Quảng cáo |
QubixApp.adsets() | Nhóm quảng cáo |
QubixApp.campaigns() | Chiến dịch |
Các phương thức chọn lọc (nối chuỗi):
| Phương thức | Tác dụng |
|---|---|
.withCondition(sql) | Lọc theo một điều kiện |
.filter(fn) | Lọc bằng một hàm |
.orderBy(field, dir) | Sắp xếp ('asc' / 'desc') |
.withLimit(n) | Giới hạn số phần tử |
.get() | Lấy một mảng các phần tử |
.first() | Lấy phần tử đầu tiên |
Các phương thức của phần tử:
| Phương thức | Hành động |
|---|---|
.pause({ duration, reason? }) | Tạm dừng |
.activate({ reason? }) | Khôi phục |
.getStatsFor(period) | Các chỉ số cho một khung ('1h'…'total') |
.getAds() | Các quảng cáo bên trong một nhóm quảng cáo / chiến dịch |
.getAdsets() | Các nhóm quảng cáo bên trong một chiến dịch |
getStatsFor trả về một tập các chỉ số cho khung đã chọn: spend, revenue, clicks, regs, deps, installs, roas, cpd, cpc, click2reg, reg2dep, ctr, i2r, i2d, c2i.
Ngữ cảnh của script
Trong các script, đối tượng ctx còn có sẵn bổ sung.
| Trường / phương thức | Mục đích |
|---|---|
ctx.state.get/set/delete/keys | Lưu trạng thái giữa các lần chạy |
ctx.fetch(url, opts?) | Một yêu cầu HTTP (máy chủ đích phải nằm trong danh sách cho phép, xem JavaScript trong cài đặt) |
ctx.now() | Thời gian hiện tại |
ctx.script | Thông tin về script hiện tại |
Đối tượng ctx (bao gồm ctx.fetch) chỉ tồn tại trong các script — nó không có sẵn bên trong các quy tắc tự động tạm dừng. Và ngay cả trong script, ctx.fetch chỉ hoạt động ở lần chạy thực trên máy chủ: trong lần chạy thử trên trình duyệt, các cuộc gọi mạng bị vô hiệu hóa, nên hãy kiểm chứng bằng một lần chạy thực.
Bộ nhớ dùng chung
Ngoài ctx.state riêng của từng script, còn có một kho lưu trữ dùng chung là ctx.state.global, hiển thị cho mọi script, quy tắc và trình xử lý trang web cùng một lúc.
| Phương thức | Hành động |
|---|---|
ctx.state.global.get(key) | Đọc một giá trị |
ctx.state.global.keys() | Liệt kê các khóa |
ctx.state.global.set(key, value) | Ghi một giá trị |
ctx.state.global.delete(key) | Xóa một giá trị |
Bất kỳ script hoặc quy tắc nào cũng có thể đọc kho dùng chung. Việc ghi (set / delete) chỉ được phép từ script hoặc quy tắc thuộc quyền sở hữu của quản trị viên — nếu không, thao tác ghi sẽ báo lỗi. Tính năng này tiện lợi cho các bảng tra cứu dùng chung: quản trị viên ghi giá trị một lần, tất cả người dùng khác đều có thể đọc.
ctx.fetch: mặc định thời gian chờ 10 giây (tối đa 30 giây), phản hồi tối đa 1 MB, không quá 20 yêu cầu mỗi lần chạy.sql: một truy vấn trả về tối đa vài nghìn hàng — quản trị viên thiết lập giới hạn chính xác trong cài đặt. Đối với các tập dữ liệu lớn, hãy tổng hợp ngay trong truy vấn.
Giá trị giới hạn chính xác được cấu hình trong Hệ thống → tab JavaScript.
sql chỉ đọc
Tagged template sql\SELECT …`thực thi một truy vấn dữ liệu chỉ đọc trong phạm vi quyền của chủ sở hữu. Nó có sẵn **cả trong các quy tắc tự động tạm dừng (Britva) lẫn trong các script người dùng** — với điều kiện thiết lập hệ thống tương ứng đã được bật. Trong lần chạy thử trên trình duyệt nó bị vô hiệu hóa (giống nhưctx.fetch), nên hãy kiểm chứng một quy tắc hoặc script có dùng sql` bằng một lần chạy thực trên máy chủ.
Danh sách đầy đủ các bảng và cột mà một truy vấn có thể truy cập được trình bày trong Bảng cho truy vấn sql.