Vì sao tập lệnh nên lắng nghe thay vì thăm dò

Mọi tập lệnh phụ thuộc vào sự đồng ý — thẻ quảng cáo, trình tải phân tích, lớp bao header bidding — đều cần biết hai điều: CMP đã có quyết định hay chưa, và quyết định đó là gì. Một sai lầm phổ biến là đọc cookie khi tải trang, hoặc thăm dò CMP bằng bộ hẹn giờ cho đến khi có kết quả. Cả hai cách đều hỏng theo những kiểu dễ đoán: định dạng cookie là nội bộ của CMP và có thể thay đổi, còn việc thăm dò hoặc kích hoạt quá sớm hoặc lãng phí thời gian chờ đợi.

IAB TCF định nghĩa một giao diện JavaScript tiêu chuẩn cho đúng công việc này: hàm __tcfapi. Hướng dẫn này đi qua các lệnh bạn thực sự cần, các sự kiện bạn sẽ nhận được và những lỗi xuất hiện nhiều nhất trong môi trường thực tế.

Phần stub và hàng đợi

Một CMP TCF được kỳ vọng đặt một stub nhỏ lên trang càng sớm càng tốt, trước khi tập lệnh CMP đầy đủ được tải. Stub định nghĩa window.__tcfapi và xếp vào hàng đợi mọi lệnh gọi được thực hiện trước khi CMP sẵn sàng. Khi CMP tải xong, nó xử lý hàng đợi và trả lời từng lệnh gọi.

Điều này giúp các tập lệnh khác có thể gọi __tcfapi ngay lập tức một cách an toàn: miễn là stub nằm trong trang trước chúng, các lệnh gọi sẽ không bị mất. Nếu một tập lệnh báo lỗi vì __tcfapi chưa được định nghĩa, thì stub đang bị thiếu hoặc tải quá muộn — hãy sửa thứ tự tải thay vì thêm cơ chế thử lại.

Các lệnh quan trọng

ping

__tcfapi('ping', 2, callback) trả về trạng thái cơ bản mà không chờ quyết định của người dùng. Phản hồi gồm cmpLoaded, cmpStatus (một trong các giá trị stub, loading, loaded hoặc error) và displayStatus (một trong visible, hidden hoặc disabled). Nó cũng báo cáo gdprApplies khi đã biết. Hãy dùng nó để chẩn đoán và để quyết định xem TCF có liên quan đến khách truy cập này hay không.

addEventListener

__tcfapi('addEventListener', 2, callback) là lệnh mà hầu hết các tích hợp nên dùng. Hàm callback nhận một đối tượng tcData và một cờ thành công, và được gọi lại mỗi khi trạng thái đồng ý thay đổi. Kể từ TCF v2.2, đây là cách được khuyến nghị để lấy dữ liệu đồng ý; lệnh getTCData cũ đã bị loại bỏ.

removeEventListener

Mỗi đối tượng tcData mang theo một listenerId. Hãy truyền nó vào __tcfapi('removeEventListener', 2, callback, listenerId) khi tập lệnh của bạn không cần cập nhật nữa — ví dụ, một trình tải dùng một lần đã đưa ra quyết định.

Đọc eventStatus

Trường then chốt trong tcData là eventStatus. Có ba giá trị:

• tcloaded — CMP tìm thấy một quyết định đã lưu hợp lệ và sẽ không hiển thị banner. Bạn có thể hành động ngay dựa trên dữ liệu.
• cmpuishown — banner đang được hiển thị. Dữ liệu phản ánh trạng thái trước đó, nhưng người dùng có thể sắp thay đổi nó.
• useractioncomplete — người dùng vừa đưa ra hoặc xác nhận một lựa chọn. Hãy hành động dựa trên dữ liệu mới.

Một trình tải điển hình chờ tcloaded hoặc useractioncomplete, sau đó kiểm tra các mục đích và nhà cung cấp mà nó cần. Nó bỏ qua cmpuishown, trừ việc có thể ghi log rằng banner đã xuất hiện.

Kiểm tra mục đích và nhà cung cấp

Bên trong tcData, sự đồng ý và lợi ích hợp pháp được cung cấp dưới dạng các đối tượng có khóa là ID:

• tcData.purpose.consents[1] — sự đồng ý cho Mục đích 1 (lưu trữ trên thiết bị).
• tcData.purpose.legitimateInterests[7] — trạng thái lợi ích hợp pháp cho Mục đích 7.
• tcData.vendor.consents[ID] và tcData.vendor.legitimateInterests[ID] — trạng thái theo từng nhà cung cấp, dùng ID trong Danh sách nhà cung cấp toàn cầu của nhà cung cấp đó.
• tcData.gdprApplies — CMP có xác định rằng GDPR áp dụng cho khách truy cập này hay không. Nếu là false, tập lệnh của bạn nên theo logic không dùng TCF.
• tcData.tcString — chuỗi đã mã hóa, mà bạn chuyển tiếp cho các đối tác cần đến nó.

Hãy kiểm tra cả mục đích lẫn nhà cung cấp. Có sự đồng ý theo mục đích mà không có sự đồng ý của nhà cung cấp, hoặc ngược lại, là chưa đủ để hầu hết nhà cung cấp xử lý dữ liệu.

Iframe và lệnh gọi giữa các khung

Quảng cáo và tiện ích thường chạy trong các iframe không thể thấy __tcfapi của trang cha. TCF giải quyết điều này bằng giao thức postMessage: CMP thêm một khung có tên __tcfapiLocator vào trang trên cùng, và mã bên trong iframe có thể tìm thấy nó, gửi thông điệp __tcfapiCall và nhận phản hồi __tcfapiReturn. Hầu hết SDK quảng cáo đã làm vậy. Nếu bạn tự viết mã iframe, hãy triển khai cùng mẫu đó thay vì đọc cookie giữa các khung.

Các lỗi thường gặp và cách nhận biết

1. Hành động dựa trên cmpuishown. Các tập lệnh tải ngay khi bất kỳ callback nào kích hoạt sẽ chạy trước khi người dùng quyết định. Hãy lọc theo eventStatus.
2. Gỡ trình lắng nghe quá sớm. Nếu bạn gỡ nó sau callback đầu tiên, bạn sẽ bỏ lỡ useractioncomplete xảy ra sau đó và tập lệnh không bao giờ được tải.
3. Bỏ qua việc rút lại sự đồng ý. Các tập lệnh chạy liên tục nên tiếp tục lắng nghe và dừng hoặc cấu hình lại khi sự đồng ý bị rút.
4. Bỏ qua gdprApplies. Ngoài các khu vực áp dụng TCF, các đối tượng mục đích có thể trống; coi điều đó là “không có đồng ý” có thể tắt doanh thu mà bạn được phép kiếm.
5. Không kiểm tra cờ thành công. Khi success là false, hãy ghi log; điều đó thường báo hiệu thiết lập CMP bị hỏng.

Kiểm thử tích hợp của bạn

Trong bảng điều khiển trình duyệt, gọi __tcfapi('ping', 2, console.log) để xác nhận CMP có mặt, sau đó đăng ký một trình lắng nghe với console.log làm callback và bấm qua banner. Bạn sẽ thấy cmpuishown rồi đến useractioncomplete ở lần truy cập đầu tiên, và tcloaded khi tải lại. Lặp lại với chấp nhận tất cả, từ chối tất cả và một lựa chọn tùy chỉnh, rồi xác nhận tập lệnh của bạn hoạt động đúng trong từng trường hợp.

Những điểm chính

• Dùng __tcfapi thay vì đọc cookie của CMP hoặc thăm dò.
• Đảm bảo stub của CMP tải trước mọi tập lệnh gọi API.
• Dùng addEventListener và chỉ hành động khi gặp tcloaded hoặc useractioncomplete.
• Kiểm tra cả trạng thái mục đích lẫn nhà cung cấp, và tôn trọng gdprApplies.
• Dùng mẫu postMessage __tcfapiLocator bên trong iframe.