API JavaScript của banner

Tổng quan

window.DuLieuCaNhan là tên công khai của mọi bản 1.x: chỉ được thêm phương thức, không đổi tên. Đối tượng có đúng sáu thành viên: version, open, getConsent, onChange, acceptAll, rejectAll. Banner không bắn sự kiện DOM nào (không có CustomEvent); muốn biết khách đổi lựa chọn thì dùng onChange.

Đặt đoạn cài banner đầu tiên trong thẻ head để window.DuLieuCaNhan có sẵn khi script của bạn chạy. Với script chạy sớm hơn hoặc bất đồng bộ, hãy kiểm tra window.DuLieuCaNhan có tồn tại trước khi gọi.

Bản chuẩn và bản ghim 1.0.0

Có hai cách cài. Bản chuẩn là một thẻ script https://cdn.dulieucanhan.vn/s/{siteKey}.js, cấu hình được ghép sẵn vào script nên banner chạy ngay. Bản ghim là https://cdn.dulieucanhan.vn/b/1.0.0/banner.pinned.js dùng với Subresource Integrity: đặt window.WDL_SITE trước, script tải cấu hình từ https://cdn.dulieucanhan.vn/s/{siteKey}.json rồi mới cấu hình banner. Cả hai có cùng sáu thành viên của window.DuLieuCaNhan và cùng thuộc tính data-wdl-*.

Bản ghim đã phát hành là bất biến: lên phiên bản mới thì phải đổi đoạn cài (địa chỉ và mã integrity). Các ví dụ dưới đây chạy được ở cả hai bản, trừ khi ghi chú khác.

version

window.DuLieuCaNhan.version // "1.1.0" (bản chuẩn) hoặc "1.0.0" (bản ghim)

Chuỗi phiên bản của bundle đang chạy. Hữu ích khi hỗ trợ: cho biết trang đang dùng bản chuẩn hay bản ghim nào.

open()

window.DuLieuCaNhan.open()

Mở hộp tuỳ chỉnh để khách xem hoặc đổi lựa chọn. Gọi khi giao diện chưa dựng xong (trang đang tải, hoặc bản ghim còn chờ cấu hình) thì banner nhớ lại và mở một lần khi giao diện được tạo. open() không bao giờ ném lỗi ra mã của trang, kể cả khi giao diện gặp lỗi.

Không cần JavaScript cho trường hợp thường gặp: phần tử bất kỳ có thuộc tính data-wdl-open sẽ mở hộp tuỳ chỉnh khi bấm, ví dụ liên kết "Quản lý cookie" ở chân trang (xem mục thuộc tính HTML).

getConsent()

const consent: Consent | null = window.DuLieuCaNhan.getConsent()

Trả về lựa chọn đang có hiệu lực, hoặc null khi chưa có lựa chọn dùng được: khách chưa quyết định, lựa chọn đã hết hạn hoặc bị yêu cầu hỏi lại (cấu hình có mức hỏi lại mới), hoặc (bản ghim) cấu hình chưa tải xong. Null nghĩa là chưa đồng ý, không phải đã từ chối.

Kiểu Consent

Ví dụ

const c = window.DuLieuCaNhan?.getConsent()
if (c && c.categories.analytics) {
  startAnalytics() // chỉ khi khách đã đồng ý loại phân tích
}

onChange(callback)

const stop: () => void = window.DuLieuCaNhan.onChange((consent: Consent) => { /* ... */ })

Đăng ký một hàm được gọi sau mỗi lần có quyết định: khách bấm nút trên banner hoặc trong hộp tuỳ chỉnh, bấm "Cho phép và xem" ở khung nội dung bị chặn, hoặc website gọi acceptAll() / rejectAll(). Hàm nhận đối tượng Consent mới và trả về một hàm để huỷ đăng ký.

• Không được gọi khi trang tải lại và banner đọc lại lựa chọn đã lưu: lúc đó hãy đọc bằng getConsent().
• Hàm của bạn bị ném lỗi thì banner bỏ qua lỗi đó và vẫn xử lý xong quyết định.
• Khi khách rút lại một loại đã đồng ý, các hàm đăng ký được gọi trước, rồi banner xoá cookie đã biết của loại đó và tải lại trang để dừng script đã chạy. Việc làm sau khi nhận sự kiện này nên ngắn.

Ví dụ

const stop = window.DuLieuCaNhan.onChange((c) => {
  if (c.categories.marketing) loadAdsTag()
})
// khi không cần nữa:
stop()

acceptAll() và rejectAll()

window.DuLieuCaNhan.acceptAll() // functional, analytics, marketing = true
window.DuLieuCaNhan.rejectAll() // cả ba = false

Thay khách ghi một quyết định cho cả ba loại không bắt buộc. Banner xử lý như khi khách bấm nút: lưu cookie wdl_consent, gửi bản ghi nhật ký tới máy chủ với nguồn api, cập nhật Google Consent Mode, gọi các hàm của onChange, rồi thả các script đang bị chặn (hoặc, nếu có loại bị rút lại, xoá cookie của loại đó và tải lại trang).

Chỉ gọi hai hàm này khi chính khách đã chọn, ví dụ từ một nút trong trang cài đặt riêng của website. Gọi mà khách chưa chọn thì bản ghi nhật ký không phản ánh ý khách. Với bản ghim, cho tới khi cấu hình tải xong hai hàm chưa làm gì.

Thuộc tính HTML data-wdl-*

Ngoài đối tượng JavaScript, banner đọc một số thuộc tính HTML. Hai bản banner đều hiểu chúng.

Chặn thủ công chỉ hoạt động với thẻ có sẵn trong HTML gốc của trang (banner cài đầu tiên trong head). Cài banner muộn qua Google Tag Manager hay plugin thì thẻ đánh dấu bị bỏ qua và banner ghi một cảnh báo trong console. Các dịch vụ có trong danh mục chuẩn của banner được chặn tự động, không cần đánh dấu.

Ví dụ

<a href="#" data-wdl-open>Quản lý cookie</a>

<script type="text/plain" data-wdl-category="analytics" src="/js/ban-do-nhiet.js"></script>

<form data-wdl-form="lien-he" action="/gui" method="post">
  <input name="email" type="email" required>
  <button type="submit">Gửi</button>
</form>

<div data-wdl-policy="privacy"></div>

Tín hiệu gửi cho nhà cung cấp

Trước mọi script khác, banner đặt Google Consent Mode mặc định: ad_storage, analytics_storage, ad_user_data, ad_personalization là denied; functionality_storage và security_storage là granted. Sau mỗi quyết định (và khi trang tải lại với lựa chọn đã lưu) banner gửi cập nhật Consent Mode theo lựa chọn: loại marketing quyết định ad_storage, ad_user_data, ad_personalization; loại analytics quyết định analytics_storage.

Nếu trang đã có sẵn hàm tương ứng, banner cũng gọi fbq("consent", "grant" hoặc "revoke") theo loại marketing, ttq.grantConsent() hoặc ttq.revokeConsent() theo loại marketing, và clarity("consent") hoặc clarity("consent", false) theo loại analytics. Lỗi trong mã của nhà cung cấp không làm hỏng banner. Banner không định nghĩa window.gtag của website.

Lưu ý

• Một trang chỉ chạy một bộ máy banner. Cài hai lần (giao diện, plugin, Google Tag Manager) thì bản sau không làm gì và ghi một dòng thông báo trong console.
• Nếu mã của trang khoá thuộc tính window.DuLieuCaNhan (chỉ đọc), API JavaScript không có nhưng việc chặn và hiện banner vẫn chạy.
• Lựa chọn của khách nằm ở cookie wdl_consent. Định dạng bên trong cookie không phải là phần công khai: đọc bằng getConsent() thay vì tự phân tích cookie.
• Bản ghi gửi về máy chủ gồm mã đồng ý, lựa chọn theo loại, đường dẫn trang (không có query string), ngôn ngữ và phiên bản cấu hình; không bao giờ có giá trị các trường của form.

Khai báo kiểu (TypeScript)

Nếu website dùng TypeScript, bạn có thể khai báo kiểu như sau (chép từ mã banner).

type Consent = {
  consentId: string
  configVersion: number
  decidedAt: string // ISO 8601
  categories: { necessary: true; functional: boolean; analytics: boolean; marketing: boolean }
}

interface BannerApi {
  version: string
  open(): void
  getConsent(): Consent | null
  onChange(cb: (consent: Consent) => void): () => void
  acceptAll(): void
  rejectAll(): void
}

declare global {
  interface Window { DuLieuCaNhan?: BannerApi }
}