Viết một script
Trình soạn thảo script là không gian làm việc nơi bạn viết code, kiểm thử trên dữ liệu trực tiếp và thiết lập lịch chạy. Màn hình được chia thành ba phần: bên trái — trợ lý AI, ở giữa — trình soạn thảo code và bảng điều khiển (console), bên phải — bảng cài đặt (siêu dữ liệu, lịch chạy, trạng thái, lịch sử chạy).
Cách tạo một script
- Mở mục Scripts và nhấn + Tạo script. Trình soạn thảo mở ra với một mẫu code.
- Trong bảng bên phải, ở phần Siêu dữ liệu, điền Tên và Mô tả của script.
- Trong trình soạn thảo ở giữa, viết phần thân của hàm
main()— chính xác những gì script cần làm (xem phần QubixApp SDK bên dưới). - Trong phần Lịch chạy, đặt tần suất script sẽ chạy tự động (xem Lịch chạy). Bạn có thể để trống nếu chỉ muốn chạy thủ công.
- Nhấn nút Chạy bên dưới trình soạn thảo để kiểm thử script trên dữ liệu trực tiếp — kết quả hiển thị trong bảng điều khiển (xem Kiểm thử script).
- Bật công tắc Đang hoạt động ở góc trên bên phải và nhấn Lưu.
Bạn có thể lưu bằng phím tắt Ctrl + S (trên macOS — Cmd + S) ngay trong trình soạn thảo, không cần di chuyển con trỏ đến nút.
Trợ lý AI
Cột bên trái là cuộc trò chuyện với trợ lý AI. Hãy mô tả nhiệm vụ bằng lời thông thường ("dừng các quảng cáo có ROAS dưới 0.5 và chi tiêu trên $20"), và trợ lý sẽ tạo ra code sẵn dùng dựa trên Qubix SDK. Nút Chèn vào Code dưới câu trả lời sẽ đưa code này thẳng vào trình soạn thảo.
Bên dưới ô nhập liệu có các câu lệnh ví dụ sẵn dùng — nhấn vào bất kỳ câu nào để bắt đầu nhanh.
Trợ lý cũng có thể nghĩ ra Tên và Mô tả cho script dựa trên code của nó — nhấn vào biểu tượng AI bên cạnh các trường này trong phần Siêu dữ liệu.
🎬 GIF: một yêu cầu tới trợ lý AI và việc chèn code vào trình soạn thảo
QubixApp SDK
Một script là một hàm main(), bên trong đó bạn làm việc với dữ liệu quảng cáo thông qua bộ lệnh QubixApp. Có sẵn ba cấp:
QubixApp.ads()— quảng cáo,QubixApp.adsets()— nhóm quảng cáo,QubixApp.campaigns()— chiến dịch.
Mỗi cấp đều trả về một tập lựa chọn có thể lọc và lặp qua. Tập lựa chọn có các phương thức:
.withCondition('...')— chọn theo một điều kiện trên các chỉ số (ví dụ,'spend_24h > 10 AND roas_24h < 0.5');.orderBy('field', 'desc')— sắp xếp;.withLimit(n)— giới hạn số lượng;.get()— lấy một mảng các phần tử;.first()— lấy phần tử đầu tiên.
Mỗi quảng cáo, nhóm quảng cáo hoặc chiến dịch đều có các hành động:
.pause({ duration: '24h', reason: '...' })— tạm dừng trong khoảng thời gian được chỉ định;.activate({ reason: '...' })— bật lại;.getStatsFor('24h')— lấy các chỉ số cho một khoảng thời gian.
Ví dụ cơ bản: tạm dừng các quảng cáo có chi tiêu trên $10 và ROAS dưới 0.5 trong ngày qua.
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' })
}
}
Thêm các đoạn code sẵn dùng có trong mục Ví dụ về script.
Tự động hoàn thành hoạt động trong trình soạn thảo: bắt đầu gõ ad. hoặc QubixApp. — Qubix sẽ gợi ý các trường và phương thức khả dụng kèm mô tả. Nhờ đó bạn không phải ghi nhớ danh sách các chỉ số trong đầu.
Truy vấn cơ sở dữ liệu
Ngoài các quảng cáo hiện tại có sẵn qua QubixApp, một script có thể đọc dữ liệu trực tiếp từ cơ sở dữ liệu Qubix bằng lệnh sql. Đây là một truy vấn chỉ đọc được viết dưới dạng tagged template:
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)
Một truy vấn trả về một mảng các hàng; mỗi hàng là một đối tượng mà khóa là tên các cột. Các giá trị bạn truyền qua ${…} được gửi dưới dạng tham số an toàn — bạn không phải escape gì bằng tay, và không thể xảy ra SQL injection. Các truy vấn là chỉ đọc: một script có thể đọc dữ liệu nhưng không thể thay đổi bất cứ thứ gì. Phạm vi mà một truy vấn có thể tiếp cận bị giới hạn bởi dữ liệu mà vai trò của bạn được phép xem.
Trạng thái giữa các lần chạy
Một script có thể ghi nhớ các giá trị giữa các lần chạy thông qua ctx.state — đây là bộ nhớ riêng của nó:
ctx.state.set('key', value)— lưu;ctx.state.get('key')— đọc;ctx.state.delete('key')— xóa.
Ví dụ, điều này cho phép bạn ghi nhớ những quảng cáo đã được xử lý và không động đến chúng lần nữa. Nội dung hiện tại của bộ nhớ hiển thị trong bảng bên phải ở phần Trạng thái — từ đó cũng có thể xóa thủ công một mục riêng lẻ.
Yêu cầu tới các dịch vụ bên ngoài
Lệnh ctx.fetch(url, opts) thực hiện một yêu cầu HTTP ra bên ngoài — ví dụ, để gửi một thông báo tới messenger hoặc gọi API của bên khác.
Các yêu cầu gửi ra ngoài chỉ được phép tới các địa chỉ trong danh sách cho phép (allowlist). Quản trị viên cấu hình nó trong Hệ thống → tab JavaScript. Nếu danh sách trống, các yêu cầu gửi ra ngoài bị vô hiệu hóa. Khi cố gắng truy cập một địa chỉ không có trong danh sách, script sẽ hiển thị một gợi ý rõ ràng trong bảng điều khiển.
Lịch chạy
Trong bảng bên phải, phần Lịch chạy đặt thời điểm script chạy tự động. Có thể có nhiều lịch chạy — ví dụ, mỗi giờ một lần và thêm vào một thời điểm cụ thể.
- Nhập lịch chạy theo định dạng cron (ví dụ,
*/5 * * * *— mỗi 5 phút) và nhấn +. - Bên dưới dòng đó, Qubix lập tức hiển thị một lời giải thích bằng lời thông thường — hãy kiểm tra xem bạn đã hiểu đúng ý nhau chưa.
- Để khỏi phải nhớ cú pháp cron, nhấn vào biểu tượng AI trong dòng và mô tả lịch chạy bằng lời ("mỗi ngày lúc 9 giờ sáng") — Qubix sẽ điền sẵn biểu thức.
Nếu không đặt lịch chạy, script sẽ không tự chạy — chỉ qua nút Chạy. Để tự động chạy hoạt động, công tắc Đang hoạt động phải được bật.
Kiểm thử script bằng nút "Chạy"
Bên dưới trình soạn thảo code có một bảng điều khiển và một nút ▶ Chạy. Nó thực thi code hiện đang có trong trình soạn thảo trên dữ liệu trực tiếp — đây là cách an toàn để kiểm thử logic mà không cần chờ đến lịch chạy. Mọi thứ script xuất ra qua console.log đều hiển thị trong bảng điều khiển cùng với thời điểm chạy, trạng thái và thời lượng.
Nút Chạy thực hiện các hành động thật. Nếu code chứa pause() hoặc activate(), các quảng cáo sẽ thực sự bị tạm dừng hoặc được bật. Để kiểm thử logic mà không gây hậu quả, trước tiên hãy chú thích (comment out) các dòng có hành động và chỉ để lại console.log.
Nút Chạy trở nên khả dụng sau khi script được lưu lần đầu tiên.
Lịch sử chạy
Phần Lần chạy trong bảng bên phải lưu lịch sử của tất cả các lần thực thi: thời điểm, trạng thái (thành công, lỗi, hết thời gian), thời lượng và số hành động đã thực hiện. Nhấn vào một hàng sẽ mở rộng toàn bộ nội dung console của lần chạy đó — tiện lợi để tìm hiểu vì sao script lại hoạt động khác thường.