Trang này đề cập đến các sự cố thường gặp trong quá trình tích hợp TRACIO và cách giải quyết chúng. TRACIO là một dịch vụ đám mây được quản lý, nên hầu hết các sự cố đều nằm ở phía client (script bị chặn, cookie, các tính năng bảo mật của trình duyệt) chứ không phải ở hạ tầng.
Script agent hoặc yêu cầu nhận dạng không tải được, hoặc console của trình duyệt hiển thị lỗi CORS đối với edge.tracio.ai.
1. Origin chưa được đưa vào danh sách cho phép của khóa
Mỗi public key có thể bị giới hạn ở một tập các origin được phép. Nếu origin của trang web của bạn không nằm trong danh sách cho phép, edge sẽ từ chối yêu cầu (403). Hãy thêm origin của bạn trong mục Request Filtering trên dashboard, hoặc xác nhận rằng khóa bạn đang dùng không bị khóa origin cho một trang web khác.
2. Ad blocker hoặc CSP chặn yêu cầu
Các tiện ích mở rộng bảo mật (uBlock Origin, AdBlock) hoặc một Content-Security-Policy nghiêm ngặt có thể chặn script agent hoặc yêu cầu mạng của nó. SDK biểu thị điều này dưới dạng lỗi blocked (xem Xử lý lỗi). Để việc chặn khó khăn hơn, hãy phân phối agent từ một subdomain first-party bằng các tùy chọn scriptUrl / endpoint.
3. Sai endpoint / khu vực
Hãy đảm bảo bạn đang trỏ đến đúng endpoint. Khi bạn đặt region, SDK sẽ giao tiếp với edge.us.tracio.ai hoặc edge.eu.tracio.ai; nếu không đặt, nó sẽ dùng edge.tracio.ai.
Điểm tin cậy luôn dưới 0.90 đối với khách truy cập quay lại.
1. Cookie không được lưu
Cookie _vid_t có thể không được đặt đúng cách. Hãy kiểm tra trong trình duyệt:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Nếu thiếu cookie, xem mục Cookie không được lưu bên dưới.
2. Workspace mới
Một workspace hoàn toàn mới có cơ sở dữ liệu khách truy cập trống, nên tất cả khách truy cập đều xuất hiện là "mới" với độ tin cậy khoảng 0.90. Sau 24–48 giờ, khách truy cập quay lại sẽ được nhận diện với độ tin cậy cao hơn.
3. Duyệt web ẩn danh/riêng tư
Ở chế độ ẩn danh, cookie và localStorage bị xóa khi phiên kết thúc. TRACIO khi đó chuyển sang chỉ so khớp bằng tín hiệu, vốn có độ tin cậy thấp hơn (thường là 0.85–0.95).
4. Trình duyệt có cơ chế chống fingerprint mạnh
Brave, Firefox (chế độ nghiêm ngặt) và Safari (ITP) sửa đổi hoặc chặn một số tín hiệu của trình duyệt. Điều này làm giảm tập tín hiệu có sẵn để so khớp. TRACIO phát hiện các trình duyệt này và điều chỉnh độ tin cậy tương ứng.
Hãy kiểm tra kết quả nhận dạng trong dashboard (Visitors / Events), hoặc xử lý
theo bản giao webhook, vốn mang theo identification.confidence,
identification.incognito và verdict bot cho mỗi sự kiện.
Khách truy cập là con người hợp lệ bị gắn cờ là bot.
1. Tiện ích mở rộng của trình duyệt sửa đổi thuộc tính navigator
Một số tiện ích mở rộng bảo mật sửa đổi navigator.userAgent, navigator.platform hoặc các thuộc tính khác. Điều này có thể kích hoạt bộ phát hiện tampering nhưng không nên tự nó kích hoạt việc phát hiện bot.
Hãy kiểm tra trường bot.type để xác định bộ phát hiện nào đã kích hoạt:
| bot.type | Nguyên nhân False Positive thường gặp | Giải pháp |
|---|---|---|
webdriver | Công cụ kiểm thử trình duyệt để lại navigator.webdriver = true | Người dùng nên tắt chế độ kiểm thử |
headless | VNC/remote desktop với kết xuất GPU bằng phần mềm | Kiểm tra xem SwiftShader/llvmpipe có phải là bộ kết xuất GPU không |
unknown | Bất thường về độ dài eval do tiện ích mở rộng của trình duyệt | Xem xét lại tiện ích mở rộng |
rateBot | Tự động làm mới trang hoặc polling quá mức | Giảm tần suất yêu cầu |
2. Môi trường doanh nghiệp với kết xuất bằng phần mềm
Các môi trường Citrix, VDI và terminal server thường dùng kết xuất GPU bằng phần mềm (SwiftShader, llvmpipe), vốn là một dấu hiệu headless. Nếu người dùng của bạn hoạt động trong các môi trường này, hãy áp dụng chính sách nhẹ nhàng hơn khi webhook cho thấy loại bot headless:
// `event` is the webhook delivery body (/docs/webhooks)if (event.bot.result === "bot" && event.bot.type === "headless") { // Software-GPU (SwiftShader/llvmpipe) VDI users can trip the headless // detector — consider applying a softer policy for these.}3. Kiểm thử tự động trên môi trường production
Nếu đội QA của bạn chạy các bài kiểm thử Selenium/Playwright trên production, chúng sẽ được phát hiện chính xác là bot. Hãy dùng một khóa riêng cho lưu lượng kiểm thử.
Cookie _vid_t biến mất giữa các lần truy cập, khiến mỗi lần truy cập đều xuất hiện là khách truy cập "mới".
1. Trang web không dùng HTTPS
Cookie _vid_t sử dụng cờ Secure và chỉ được đặt qua HTTPS. Hãy đảm bảo trang web của bạn dùng HTTPS.
2. Tải trong ngữ cảnh cross-site
TRACIO đặt SameSite=Lax cho cookie. Nếu agent được tải trong một ngữ cảnh cross-site nghiêm ngặt, cookie có thể bị chặn. Việc phân phối agent từ một subdomain first-party (qua scriptUrl / endpoint) giữ cho nó ở trạng thái same-site.
3. Safari ITP
Intelligent Tracking Prevention (ITP) của Safari có thể giới hạn thời gian tồn tại của các cookie do client đặt. TRACIO còn phát hành _vid_t từ phía server qua header Set-Cookie và phản chiếu UID sang localStorage, nhờ đó danh tính vẫn tồn tại ngay cả khi cookie bị giới hạn.
4. Trình duyệt xóa cookie
Một số trình duyệt (Brave, Firefox Focus) xóa cookie khi phiên kết thúc. Người dùng có cài đặt bảo mật nghiêm ngặt sẽ luôn xuất hiện là khách truy cập mới.
tracio.getResult() mất hơn 500ms để trả về.
1. Mạng đến edge chậm
Hãy kiểm tra độ trễ khứ hồi đến edge khu vực của bạn:
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health2. Việc thu thập tín hiệu mất quá lâu
Một số tín hiệu có timeout. Trên các thiết bị chậm, việc thu thập có thể mất hơn 200ms. Các tín hiệu dễ làm tăng độ trễ nhất là fingerprint âm thanh (AudioContext bị tạm dừng trên iOS), probe WebRTC/TURN, phát hiện font và định thời DRM. Chúng đều bị giới hạn bởi timeout và không bao giờ chặn vô thời hạn.
Một số tín hiệu trả về trạng thái không thành công (ví dụ "not available" hoặc "timeout").
Lỗi tín hiệu là điều được dự kiến và được xử lý một cách nhẹ nhàng — hệ thống điều chỉnh độ tin cậy dựa trên các tín hiệu có sẵn. Các ví dụ thường gặp: canvas bị CSP chặn, AudioContext bị timeout trên iOS, WebGPU không được hỗ trợ trên hầu hết các trình duyệt, Client Hints không khả dụng bên ngoài Chromium. Không cần hành động gì trừ khi các tín hiệu quan trọng (canvas, WebGL, audio) liên tục thất bại ở nhiều khách truy cập.
Nếu bạn gặp một sự cố không được đề cập ở đây: