Tài liệu tham chiếu Browser SDK
Tài liệu tham chiếu cho Browser SDK, window.sdk: cách hiển thị lời mời cài đặt PWA từ trang,
đăng ký khách truy cập nhận push, gửi sự kiện và các cài đặt cần thiết. Để xem phần giới thiệu
tổng quan, hãy xem Browser SDK; để kết nối với prelanding của riêng bạn, xem
SDK trên prelanding của bạn.
Cài đặt window.pwaConfig
SDK đọc cài đặt từ đối tượng window.pwaConfig, được bạn thiết lập trên trang
trước thẻ script. Trên các trang do Qubix phục vụ, đối tượng này được điền tự động;
trên prelanding của riêng bạn, bạn tự thiết lập.
| Trường | Mục đích |
|---|---|
pwaId | Định danh PWA. Bắt buộc để cài đặt và nhận push |
domain | Tên miền của trang. Bắt buộc cho manifest và push |
vapidKey | Khoá dùng cho push. Thường được nhúng tự động khi /sdk.js tải — không cần thiết lập thủ công |
offerId | Offer (nếu cần truyền tường minh) |
campaignId | Chiến dịch (nếu cần truyền tường minh) |
params | Thẻ theo dõi bổ sung |
previewMode | Chế độ xem trước: sự kiện không được gửi |
Định danh PWA (pwaId) được lấy từ thẻ ứng dụng trong mục PWA Apps.
Đăng ký push
sdk.subscribePush() yêu cầu trình duyệt cấp quyền thông báo và tạo một subscription.
Bạn phải gọi hàm này tường minh — ví dụ, khi người dùng nhấn nút. Hàm không tự kích hoạt.
const subscription = await sdk.subscribePush()
if (subscription) {
// khách truy cập đã cho phép thông báo và đã đăng ký
}
Những gì diễn ra bên trong:
- Hộp thoại yêu cầu quyền của trình duyệt được hiển thị.
- Nếu khách truy cập chấp nhận, subscription được tạo và gửi đến Qubix.
- Gọi lại nhiều lần là an toàn: nếu khách truy cập đã đăng ký, hộp thoại sẽ không hiển thị lại.
Không cần cài đặt ứng dụng để nhận push — khách truy cập có thể đăng ký trên trang thông thường.
Push chỉ hoạt động qua kết nối bảo mật (HTTPS) và trên tên miền đã được thiết lập trong Qubix. Tìm hiểu thêm tại SDK trên prelanding của bạn.
Cài đặt PWA
Nếu window.pwaConfig có pwaId, SDK sẽ cung cấp các phương thức sdk.pwa:
| Phương thức | Chức năng |
|---|---|
sdk.pwa.init() | Chuẩn bị: đăng ký service worker và gắn manifest ứng dụng |
sdk.pwa.install() | Hiển thị hộp thoại hệ thống để cài đặt ứng dụng |
sdk.pwa.canInstall() | Kiểm tra xem việc cài đặt có khả dụng ngay lúc này không |
sdk.pwa.isInstalled() | Kiểm tra xem ứng dụng đã được cài đặt chưa |
sdk.pwa.open() | Mở ứng dụng đã cài đặt |
init, install và isInstalled là bất đồng bộ — hãy gọi chúng với await. canInstall và open trả về giá trị ngay lập tức.
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
Hộp thoại cài đặt do chính trình duyệt hiển thị, nên các quy tắc của trình duyệt áp dụng: HTTPS, manifest đã được gắn (SDK thực hiện việc này cho bạn) và thường là một hành động của khách truy cập trên trang (nhấp chuột, cuộn trang). Đó là lý do nút cài đặt thường được gắn với một thao tác chủ động.
Sự kiện
SDK tự động báo cáo các thời điểm quan trọng đến analytics — chúng hiển thị trong báo cáo và trong luồng sự kiện:
| Sự kiện | Thời điểm |
|---|---|
campaign_visit | Lượt truy cập trang (gửi tự động) |
push_prompt_shown | Hộp thoại yêu cầu quyền push được hiển thị |
push_allow | Khách truy cập đã cho phép push |
push_deny | Khách truy cập đã từ chối push |
push_ignored | Khách truy cập đã đóng hộp thoại mà không chọn |
install_accepted | Khách truy cập đồng ý cài đặt ứng dụng |
install_rejected | Khách truy cập từ chối cài đặt |
Bạn có thể gửi sự kiện tuỳ chỉnh theo cách thủ công:
sdk.sendEvent('my_button_click', { place: 'hero' })
Dữ liệu lưu lượng
Các phương thức hỗ trợ để đọc ngữ cảnh click:
| Phương thức | Trả về |
|---|---|
sdk.getOffer() | Offer hiện tại (id và URL) |
sdk.getPwa() | PWA hiện tại |
sdk.getPiuid() | ID khách truy cập |
sdk.getTrackingParams() | Thẻ tracker đi kèm theo click |
sdk.buildOfferUrl(url) | Tạo URL offer với các thẻ được truyền theo |
sdk.showStore() | Chuyển đến thẻ cửa hàng PWA |
Những gì SDK tự thực hiện
Khi không có lệnh gọi nào từ phía bạn, khi tải trang SDK sẽ thu thập dữ liệu thiết bị, phân tích
các thẻ theo dõi từ URL, gắn manifest ứng dụng (nếu pwaId được thiết lập) và gửi sự kiện
campaign_visit. Việc cài đặt và đăng ký push không tự khởi động — bạn kích hoạt chúng từ code.