Tham chiếu phán quyết

Mỗi phán quyết của Fraud Prevention — dù được gửi tới callback onVerdict của bạn trong Web SDK hay được kéo từ Data API — đều là cùng một đối tượng BotVerdict. Trang này mô tả từng trường và cách hành động với nó.

{
  "is_bot": false,
  "score": 18,
  "level": "low",
  "action": "record_only",
  "reasons": [],
  "consistency": { "ok": true },
  "degraded": false,
  "verdict_id": "vd_3f9c0a7e5b1d4c2a9e8f7b6a",
  "verdict_token": "vt1.eyJ2Ijoi...",
  "verdict_token_exp": 1767225600
}

Các trường

Trường	Kiểu	Mô tả
is_bot	boolean	Phán quyết chính. true = lượt truy cập bị đánh giá là lưu lượng tự động hoặc không hợp lệ; false = trông giống người thật. Đây là trường mà hầu hết các tích hợp dựa vào để rẽ nhánh.
score	number (0–100)	Mức độ đáng ngờ của lượt truy cập. Càng cao càng đáng ngờ. Dùng nó để đặt ngưỡng riêng của bạn — ví dụ loại bỏ các lượt truy cập vượt một mốc cắt mà bạn chọn. Giá trị cụ thể do mô hình rủi ro của chúng tôi tạo ra và không nhằm để bị suy diễn ngược.
level	enum	Phân dải thô của score: low, medium, high, critical. Tiện khi bạn muốn dùng các nhóm thay vì một con số thô.
action	enum	Cách xử lý được khuyến nghị của chúng tôi cho lượt truy cập: record_only, challenge, flag, hoặc deny. Xem bên dưới. Hãy coi các giá trị không xác định là flag, để tích hợp của bạn vẫn hoạt động nếu có giá trị mới được thêm vào.
reasons	string[]	Tối đa ba nhóm lý do tổng quát giải thích một phán quyết rủi ro. Rỗng với các lượt truy cập sạch.
consistency	object	Một kết luận về tính nhất quán xuyên tín hiệu. Hãy đọc consistency.ok (boolean): true = các tín hiệu của lượt truy cập khớp với kỳ vọng; false = có gì đó không khớp và lượt truy cập đáng được soi xét thêm. Phần chi tiết nội bộ phía sau kết luận này không được lộ ra.
degraded	boolean	true khi phán quyết không thể được tính toán đầy đủ (dịch vụ không truy cập được, lỗi, v.v.) và một giá trị dự phòng thận trọng được trả về. Hãy coi phán quyết suy giảm là "không rõ", chứ không phải "sạch".
verdict_id	string	Id duy nhất của phán quyết này. Dùng nó để tra cứu phán quyết sau này bằng Data API.
verdict_token	string	Bằng chứng có chữ ký của phán quyết này, để máy chủ của bạn xác minh. Xem Xác minh phía máy chủ. Không có trên các phán quyết dự phòng.
verdict_token_exp	number	Thời điểm Unix (giây) mà verdict_token hết hạn.

action — nên làm gì

action là khuyến nghị của chúng tôi; bạn vẫn nắm quyền quyết định cuối cùng.

action	Ý nghĩa	Nên làm gì
record_only	Lượt truy cập trông bình thường.	Tiếp tục như thường. Chỉ ghi lại phán quyết phục vụ báo cáo và đối soát.
flag	Lượt truy cập đáng ngờ nhưng chưa kết luận là xấu.	Vẫn phục vụ trang, nhưng đánh dấu lượt truy cập là chất lượng thấp — loại nó khỏi số liệu của bạn, tách nó ra khỏi các luồng phía sau, và tính trọng số cho nó trong các quyết định của riêng bạn (ví dụ phân bổ chuyển đổi hoặc mức độ tin tưởng lượt truy cập).
challenge	Lượt truy cập đạt ngưỡng xác minh của bạn (mặc định là rủi ro cao).	Yêu cầu thêm một lần xác minh trước khi coi khách truy cập là người thật. Khi hành động xử lý của ứng dụng được đặt là challenge, Web SDK sẽ chạy việc này giúp bạn (xem Nâng cấp xác minh); nếu không, hãy áp dụng cổng chặn của riêng bạn.
deny	Lượt truy cập khớp một quy tắc chặn — ví dụ một mục trong danh sách chặn hoặc một chính sách bạn cấu hình để chặn.	Không phục vụ nội dung được bảo vệ. Không có challenge nào được đưa ra. Các phiên bản SDK cũ chuyển nguyên giá trị này, nên hãy xử lý nó trong onVerdict.

Hành động xử lý có thể cấu hình

action báo cáo gì cho một lượt truy cập rủi ro cao là cấu hình theo từng ứng dụng, được đặt trong bảng điều khiển dưới phần chi tiết ứng dụng của bạn. Phán quyết là quyền uy ở phía máy chủ: action chỉ trở thành challenge hoặc flag khi lượt truy cập đạt dải rủi ro cao và ứng dụng của bạn được cấu hình với hành động tương ứng. Dưới dải đó, phán quyết vẫn là record_only.

Cấu hình	action trả về khi rủi ro cao	Ý nghĩa
record_only (mặc định)	record_only	Chỉ ghi nhận. Phán quyết được ghi lại phục vụ báo cáo và đối soát; không yêu cầu gì ở khách truy cập.
challenge	challenge	Kích hoạt một CAPTCHA xác minh lại. Web SDK bật lên một challenge (kiểu dáng do challengeConfig của SDK điều khiển).
flag	flag	Đánh dấu lượt truy cập. Phán quyết mang flag; tích hợp của bạn tự quyết cách hành động với nó (chặn / phân tách / xử lý).

Vì quyết định được đưa ra ở phía máy chủ, mã của bạn vẫn đơn giản: đọc verdict.action trong onVerdict và hành động theo nó — tiếp tục, chặn, hoặc để SDK hiển thị một challenge. Bạn không cần tự suy ra lại rủi ro.

Ngưỡng và loại xác minh

Khi hành động là challenge, cùng mục đó trên bảng điều khiển sẽ có thêm hai cài đặt:

• Ngưỡng xác minh — mức rủi ro nào thì trả về hành động đã cấu hình. Mặc định là rủi ro cao trở lên. Chế độ nghiêm ngặt áp dụng cả cho lượt truy cập rủi ro trung bình: chặn được nhiều trình thu thập và tác nhân AI hơn, nhưng nhiều khách truy cập thật sẽ thấy xác minh hơn.
• Loại xác minh — loại CAPTCHA tối thiểu hiển thị khi nâng cấp: thanh trượt (mặc định), xoay, nhấp hoặc nhấp 3D. Loại càng mạnh, công cụ tự động và AI càng khó giải.

escalate_result

Có mặt sau khi một lần nâng cấp captcha được quản lý chạy — tức là khi action là challenge và SDK đã chạy captcha. null khi không có lần nâng cấp nào. Cũng được gửi tới onEscalateDone(passed, detail).

trường	mô tả
passed	khách truy cập có vượt qua captcha hay không
token	captcha pass token — xác minh nó ở phía máy chủ để xác nhận đã vượt qua (đừng chỉ tin vào passed ở phía client)
challenge_id	id challenge của captcha
cid	click id mà lần nâng cấp này gắn với, nếu có click token

reasons — nhóm lý do

reasons cho bạn biết, ở mức tổng quát, vì sao một lượt truy cập trông có rủi ro. Nó chứa tối đa ba nhóm, mạnh nhất trước. Nó không bao giờ chứa từng tín hiệu riêng lẻ hay phần phân tách điểm số.

Nhóm	Ý nghĩa
automation	Dấu hiệu của công cụ tự động, như trình duyệt chạy bằng script hoặc headless.
network	Mạng trông có rủi ro hoặc không nhất quán, như proxy, mạng trung tâm dữ liệu hoặc mạng ẩn danh, hoặc một địa chỉ bị chặn.
abnormal_requests	Mẫu request bất thường, như quá nhiều request, thất bại lặp lại, hoặc có lịch sử lưu lượng tự động.
device	Thiết bị hoặc môi trường của nó không đáng tin cậy, hoặc không nhận diện được.
behavior	Lượt truy cập không hành xử như người, ví dụ hoàn toàn không có tương tác hoặc một liên kết bị dùng lại.
other	Mọi lý do khác, bao gồm các quy tắc của riêng bạn và phán quyết dự phòng.

Hãy coi danh sách này là lời giải thích phục vụ báo cáo, không phải tín hiệu để xây dựng quy tắc. Thay vào đó, hãy rẽ nhánh theo is_bot, action hoặc score. Các nhóm mới có thể được thêm vào sau.

Xác minh phía máy chủ

Mọi thứ trang nhận được đều có thể bị khách truy cập thay đổi. Nếu bạn chặn nội dung (chỉ người thật mới được xem một trang, một phản hồi API hoặc một bản tải xuống), đừng tin cờ is_bot trong trình duyệt. Hãy gửi verdict_token tới máy chủ của bạn và xác minh nó ở đó:

1. Trong onVerdict, gửi verdict.verdict_token tới backend của bạn, ví dụ trong một header hoặc cookie.
2. Backend của bạn gọi POST /v1/bot/verdict/verify với token và địa chỉ IP của khách truy cập.
3. Chỉ phục vụ nội dung khi phản hồi có valid: true và phán quyết được bạn chấp nhận (ví dụ verdict.is_bot là false).

Token được ràng buộc với ứng dụng của bạn, với phán quyết này và với mạng của khách truy cập, và hết hạn sau một thời gian ngắn (mặc định 10 phút). Theo mặc định một token có thể được kiểm tra nhiều lần, nên một token có thể dùng cho các lượt xem trang trong một lượt truy cập. Truyền consume: true khi token chỉ được dùng một lần, ví dụ cho việc gửi biểu mẫu.

Nếu sau đó khách truy cập vượt qua challenge nâng cấp, token vẫn thể hiện phán quyết ban đầu. Hãy xác minh cả captcha pass token trong escalate_result bằng API phía máy chủ của captcha.

level so với score

level chỉ là một cách phân dải của score, cung cấp cho tiện:

level	Dùng khi
low	Coi như lưu lượng sạch.
medium	Giáp ranh — ghi nhận thì ổn, cân nhắc loại khỏi các phễu giá trị cao.
high	Đáng ngờ rõ rệt — gắn cờ và loại bỏ.
critical	Gần như chắc chắn không hợp lệ — gắn cờ/loại bỏ và, lý tưởng nhất, nâng cấp xác minh.

Chọn trường phù hợp với pipeline của bạn

• Cổng chặn có/không đơn giản → rẽ nhánh theo is_bot.
• Theo khuyến nghị → rẽ nhánh theo action.
• Ngưỡng tùy chỉnh → rẽ nhánh theo score (hoặc level để chia nhóm).

Xử lý phán quyết suy giảm

Khi degraded là true, phán quyết chưa được tính toán đầy đủ. Giá trị dự phòng được cố ý đặt thận trọng (is_bot: false, action: record_only) nên người dùng thật không bao giờ bị chặn. Trong báo cáo, hãy coi những lượt này là không rõ thay vì tính chúng là lưu lượng đã xác nhận sạch.

Bước tiếp theo

• Web SDK — nhận phán quyết trên trang của bạn
• Data API — kéo phán quyết và thống kê ở phía máy chủ