@zalo-ads/pixel-sdk

Thư viện tích hợp Zalo Ads Pixel dành cho các dự án React, Angular, Zalo Mini App và mọi dự án sử dụng JS module.

Cài đặt

npm install @zalo-ads/pixel-sdk

Khởi tạo

Gọi init() một lần duy nhất trong vòng đời ứng dụng, tại điểm khởi tạo sớm nhất có thể:

import { ZaloAdsPixel } from "@zalo-ads/pixel-sdk";

ZaloAdsPixel.init({ pixelId: "YOUR_PIXEL_ID" });

| Tuỳ chọn | Kiểu | Mặc định | Mô tả | |---|---|---|---| | pixelId | string | | Bắt buộc. Pixel ID của tài khoản quảng cáo. | | debug | boolean | false | Ghi nhật ký các mốc thực thi ra console. Pixel ID luôn được rút gọn, chỉ hiển thị bốn ký tự cuối. | | readyTimeoutMs | number | 10000 | Thời gian chờ tối đa để pixel sẵn sàng, áp dụng cho hai phương thức trả về giá trị. |

init() phát sinh ngoại lệ trong hai trường hợp: tham số khởi tạo không hợp lệ, hoặc môi trường thực thi không phải trình duyệt. Cả hai đều được phát hiện ngay trong lần chạy đầu tiên. Các phương thức còn lại không phát sinh ngoại lệ ra ứng dụng.

Lời gọi init() thứ hai với cùng pixel ID chỉ cập nhật cờ debug. Với pixel ID khác, thư viện ghi cảnh báo và bảo toàn cấu hình của lần khởi tạo đầu tiên.

Nếu trang đã nhúng sẵn thẻ script pixel, thư viện nhận diện và không thêm thẻ thứ hai.

Các phương thức

Các phương thức ghi nhận có thể được gọi ngay sau init(), kể cả khi script pixel chưa tải xong. Lời gọi được đưa vào hàng đợi và gửi đi theo đúng thứ tự khi pixel sẵn sàng xử lý.

track(event, parameters?)

Ghi nhận một sự kiện chuyển đổi.

ZaloAdsPixel.track("ViewContent", { content_id: "SKU-123", value: 250000, currency: "VND" });
ZaloAdsPixel.track("Purchase", { value: 1200000, currency: "VND", quantity: 2 });
ZaloAdsPixel.track("KhuyenMaiTet");

Thư viện định nghĩa mười bảy sự kiện chuẩn để trình soạn thảo gợi ý:

| Nhóm | Sự kiện | |---|---| | Thương mại điện tử | ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, CustomizeProduct | | Khách hàng tiềm năng | Lead, CompleteRegistration, Contact, SubmitApplication, Schedule, FindLocation | | Tương tác | Search, StartTrial, Subscribe | | Khác | Donate |

Tên sự kiện tuỳ chỉnh vẫn được chấp nhận. Tham số được chuyển nguyên vẹn xuống pixel, không chuẩn hoá và không bổ sung trường.

pageView()

Ghi nhận một lượt xem trang.

ZaloAdsPixel.pageView();

Pixel tự ghi nhận lượt xem trang đầu tiên khi tải. Phương thức này dành cho ứng dụng một trang, được gọi tại mỗi lần điều hướng phía client:

// React Router
useEffect(() => {
  ZaloAdsPixel.pageView();
}, [location.pathname]);

addPixelId(pixelId)

Đăng ký thêm một pixel ID tại thời điểm chạy:

ZaloAdsPixel.addPixelId("ANOTHER_PIXEL_ID");

Áp dụng khi một trang cần báo cáo về nhiều tài khoản quảng cáo. Phương thức này bổ sung chứ không thay thế pixel ID đã khởi tạo.

isFromAds()

Xác định phiên hiện tại có đến từ quảng cáo hay không.

const fromAds = await ZaloAdsPixel.isFromAds();

if (fromAds === true) showAdsWelcomeBanner();
else showDefaultBanner();

getSourceCampaign()

Trả về nguồn chiến dịch của phiên hiện tại.

const source = await ZaloAdsPixel.getSourceCampaign();

Hai phương thức trên trả về Promise do phụ thuộc vào thời điểm pixel sẵn sàng phản hồi. Ứng dụng có thể gọi ngay sau init() mà không cần tự theo dõi trạng thái sẵn sàng.

Giá trị undefined biểu thị trạng thái không xác định, phân biệt với false hoặc chuỗi rỗng vốn là giá trị hợp lệ do pixel trả về. Trạng thái này xảy ra khi script không tải được, khi vượt quá readyTimeoutMs, hoặc khi được gọi trước init(). Cả hai phương thức không bao giờ reject.

TypeScript

Thư viện cung cấp sẵn khai báo kiểu, không yêu cầu cài đặt gói @types riêng:

import { ZaloAdsPixel, type ZaloAdsPixelParameters } from "@zalo-ads/pixel-sdk";

Các kiểu được xuất ra: ZaloAdsPixelInitOptions, ZaloAdsPixelParameters, ZaloAdsPixelStandardEvent, ZaloAdsPixelEvent, ZaloAdsPixelClient.

Định dạng phân phối

| Cách nạp | Tệp | |---|---| | import (ESM) | dist/pixel-sdk.js | | require (CommonJS) | dist/pixel-sdk.cjs | | Thẻ script (UMD) | dist/pixel-sdk.umd.js |