Dữ liệu của bạn, ngay nơi bạn ra quyết định
Mỗi lần nhận diện đều có thể đến hệ thống của bạn theo hai đường: được đẩy tới máy chủ của bạn ngay khi nó xảy ra, hoặc do chính bạn kéo về đúng giây bạn quyết định. Cả hai kênh đều mang cùng những con số — và điều đó được khóa lại bằng một bài kiểm thử, chứ không phải bằng một lời hứa.
Đẩy hay kéo
Webhook đẩy sự kiện tới bạn ngay khi chúng diễn ra. Data API cho phép bạn hỏi đúng lúc bạn cần câu trả lời. Phần lớn đội ngũ chạy cả hai: webhook để ghi nhận và phản ứng, Data API để kiểm tra ngay trong luồng.
Webhook — đẩy, theo thời gian thực
Chúng tôi POST một sự kiện JSON có chữ ký tới endpoint của bạn ngay khi có chuyện xảy ra: một khách truy cập được nhận diện, một vụ chiếm đoạt tài khoản bị gắn cờ, một đợt tấn công bot bắt đầu. Không cần polling, không cần lên lịch.
Phù hợp nhất cho: ghi nhận mọi lượt truy cập, phản ứng với tấn công, đổ dữ liệu về kho dữ liệu hoặc SIEM của bạn.
Độ trễ gửi p50 44–140 ms, từ sự kiện tới endpoint của bạn.
Data API — kéo, theo yêu cầu
Một API riêng tư giữa máy chủ với máy chủ. Backend của bạn xác thực bằng secret key và đọc đúng những gì chúng tôi biết về một khách truy cập vào đúng giây nó ra quyết định — thường là bên trong handler đăng nhập hoặc thanh toán.
Phù hợp nhất cho: một lần kiểm tra ngay trong luồng, trước khi bạn tính tiền thẻ, duyệt một lượt đăng ký hay mở khóa một tài khoản.
Có từ gói Pro.
Bốn loại sự kiện, một phong bì
Mọi lần gửi đều đến trong cùng một phong bì, với loại sự kiện nằm cả trong body lẫn trong header X-Tracio-Event-Type — nên một handler duy nhất có thể định tuyến cả bốn.
Khách truy cập được nhận diện
Sự kiện cốt lõi: một lượt truy cập đã được chấm điểm. Nó mang theo ID khách truy cập, trình duyệt và hệ điều hành, vị trí và mạng, phán quyết bot cùng quyết định rủi ro. Được gửi theo pha — sự kiện chính khi trang tải xong, rồi pha muộn hoặc pha hiệu chỉnh khi bằng chứng đến chậm làm thay đổi phán quyết. Ghép các pha lại với nhau qua requestId.
identificationChiếm đoạt tài khoản
Bộ phát hiện chiếm đoạt tài khoản đã kích hoạt trên một lượt truy cập: thiết bị đứng sau một tài khoản đã biết không còn giống thiết bị vốn sở hữu nó. Nó đến như một sự kiện riêng, kèm bối cảnh tài khoản, thay vì ẩn bên trong body của sự kiện nhận diện.
account_takeoverTấn công bot
Một đợt tăng vọt lưu lượng tự động trên workspace của bạn. Sự kiện này không có lượt truy cập nào đứng sau — nó là cảnh báo ở cấp workspace, nên các khối dữ liệu về lượt truy cập đơn giản là vắng mặt khỏi body thay vì đến như những vỏ rỗng với điểm số bằng không.
attack_detectedThay đổi uy tín
Một hồ sơ chuyển giữa các dải uy tín. Cùng phong bì với cảnh báo tấn công — một sự kiện ở cấp hồ sơ, không kèm lượt truy cập, mang theo dải mới và dải trước đó.
reputation_changedMột lần gửi, đã lược bớt
Đây là body cơ sở. Pro bổ sung visit velocity; Business bổ sung mã lý do phán quyết, tín hiệu hành vi, Guidance và dữ liệu thiết bị xuyên trình duyệt vào đúng hình dạng ấy — các khối mới xuất hiện, còn những đường dẫn sẵn có thì không bao giờ dịch chuyển.
{ "version": 2, "event": "identification", "eventId": "req_8f21c4:primary", "requestId": "req_8f21c4", "phase": "primary", "visitorId": "3f9a1b2c4d5e6f70", "timestamp": "2026-07-30T12:00:00Z", "geo": { "country": "DE", "city": "Berlin", "timezone": "Europe/Berlin" }, "network": { "vpn": true, "proxy": false, "tor": false, "datacenter": false }, "bot": { "result": "human", "score": 12 }, "identification": { "confidence": 0.97, "incognito": false }, "decision": { "action": "suspicious", "riskScore": 65.9 }}Mỗi request mang hai chữ ký
X-Tracio-Signature là HMAC-SHA256 tính trên dấu thời gian chữ ký ghép với body thô của request, khóa bằng webhook secret của bạn — nó chứng minh bên gửi biết cái secret mà cả hai bên cùng giữ. X-Tracio-Signature-Ed25519 là chữ ký nền tảng: bạn xác minh nó bằng khóa công khai lấy từ một endpoint well-known, nên phía bạn không phải lưu bí mật nào cả. Dấu thời gian là một phần của nội dung được ký, và chính điều đó khiến một bản ghi cũ trở nên vô dụng khi bị phát lại.
Hãy xác minh trên đúng các byte thô của request — JSON được tuần tự hóa lại sẽ đổi byte và chữ ký sẽ không khớp. Các lần gửi lại mang cùng X-Tracio-Event-Id, nên hãy khử trùng lặp theo giá trị đó.
Header trên mỗi lần gửi
X-Tracio-Signature: t=1753444800,v1=5257a869e7ecebed...X-Tracio-Signature-Ed25519: t=1753444800,kid=k1,v1=0Zx0M0n8...X-Tracio-Event-Type: identificationX-Tracio-Event-Id: req_8f21c4:primaryX-Tracio-Delivery-Attempt: 1X-Tracio-Payload-Version: 2Được dựng để không đánh mất sự kiện
Việc gửi chạy trên một cụm máy riêng, và nguồn sự thật là hàng đợi — chứ không phải bộ nhớ của một tiến trình. Đó là thứ khiến at-least-once trở nên có thật: nếu một node gửi chết giữa chừng, sự kiện vẫn nằm trong hàng đợi và một node khác nhặt nó lên.
Cơ chế thử lại khớp với sự cố thật
5 giây, 30 giây, 2 phút, 10 phút, 30 phút, 2 giờ, 6 giờ. Những lần thử đầu tiên rơi vào trong vòng một phút, nên một lần khởi động lại ngắn của dịch vụ bên bạn chẳng khiến bạn mất gì. Mỗi quãng nghỉ được chọn ngẫu nhiên giữa một nửa giá trị ghi trong danh sách và giá trị đầy đủ, để các lần thử lại không ập về thành một loạt duy nhất sau sự cố.
Tự động tắt mà không bắn nhầm
Một webhook chỉ bị tắt khi số lần thất bại vừa chạm ngưỡng vừa đã kéo dài ít nhất 15 phút liên tiếp — một đợt dồn các lần gửi trong lúc khởi động lại sẽ không giết chết tích hợp. Mã 410 Gone thì tắt ngay lập tức. Dashboard hiển thị lý do, mã phản hồi và một nút bật lại.
Xoay secret không để lại khoảng trống
Sau khi xoay, cả hai secret đều còn hiệu lực trong 24 giờ và header mang cả hai chữ ký, nên khớp một trong hai là đủ. Bạn cập nhật cấu hình ngay trong cửa sổ đó thay vì phải chạy đua với thời điểm chuyển đổi; “Revoke now” cắt ngắn cửa sổ khi bạn cần nó biến mất ngay.
Một nhật ký gửi mà bạn đọc được
Mọi lần thử — mã phản hồi, thời lượng, nội dung lỗi — đều hiện ra theo từng webhook trong dashboard, ngay cạnh một thao tác kiểm thử gửi payload mẫu có chữ ký tới endpoint của bạn để bạn xác nhận bộ xác minh của mình trước khi chạy thật.
Hỏi đúng vào lúc bạn ra quyết định
Một API riêng tư giữa máy chủ với máy chủ tại api.tracio.ai. Backend của bạn xác thực bằng secret key và đọc dữ liệu của chính mình. Nó cố ý không gửi bất kỳ header CORS nào: một secret key mở quyền truy cập vào mọi thứ trong workspace của bạn và không bao giờ được để lọt tới trình duyệt. Có từ gói Pro.
| Phương thức | Đường dẫn | Trả về |
|---|---|---|
| GET | /v1/visitors/{visitorId} | Tóm tắt khách truy cập: lần đầu và lần cuối nhìn thấy, số lượt truy cập, số IP và quốc gia duy nhất, trình duyệt và thiết bị, lịch sử rủi ro — cùng phiên gần nhất của họ. |
| GET | /v1/visitors/{visitorId}/sessions | Danh sách phiên với phân trang bằng con trỏ và bộ lọc theo khoảng ngày, kết quả bot và điểm rủi ro tối thiểu. |
| GET | /v1/visitors/{visitorId}/sessions/latest | Phiên gần nhất dưới dạng một đối tượng đơn, không có lớp bao danh sách. |
| GET | /v1/sessions/{requestId} | Một phiên cụ thể. Truyền kèm visitorId và việc tra cứu sẽ đi qua chỉ mục khách truy cập thay vì toàn bộ lịch sử của bạn. |
| GET | /v1/visitors/{visitorId}/velocity | Hoạt động trong một cửa sổ — 1h, 24h hoặc 7d: bao nhiêu lượt truy cập, từ bao nhiêu IP, từ bao nhiêu quốc gia, dưới bao nhiêu tài khoản. |
Kiểm tra một khách truy cập ở bước thanh toán
Lệnh gọi điển hình: bên trong handler thanh toán của bạn, trước khi bạn ủy quyền thẻ. Một request, một câu trả lời, và khối meta báo lại đúng cửa sổ mà bạn thực sự nhận được — nếu bạn hỏi sáu tháng trong khi gói của bạn lưu 30 ngày, nó trả về 30 ngày và nói rõ điều đó.
Request
# Inside your checkout handler, before you authorize the cardcurl -s -H "Authorization: Bearer $TRACIO_SECRET_KEY" \ "https://api.tracio.ai/v1/visitors/3f9a1b2c/velocity?window=24h"Phản hồi
{ "window": "24h", "events": 128, "uniqueIps": 4, "uniqueCountries": 2, "uniqueAccounts": 1, "meta": { "plan": "business", "retentionDays": 30 }}Cùng những con số ở mọi nơi
Một lượt truy cập được chấm 65,9 trong dashboard của bạn cũng được chấm 65,9 trong Data API và 65,9 trong body webhook. Hai lần kết xuất độc lập hoàn toàn có thể trôi xa nhau — thang đo là kiểu kinh điển, kênh này đưa bạn 0,93 trong khi kênh kia nói 93 — nên một bài kiểm thử tương đương sẽ dựng một lượt truy cập, kết xuất nó qua cả hai kênh rồi so sánh các trường công khai trên JSON thô. Sự khớp nhau đó được cưỡng chế, chứ không phải chỉ được tuyên bố.
Lời khuyên, không chỉ những con số
Điểm số cho bạn biết chúng tôi đã thấy gì. Guidance cho bạn biết nên làm gì với điều đó, cho bốn quyết định thực sự tốn tiền — được tính bằng các quy tắc có đánh phiên bản, kèm theo lý do.
Nhận khoản thanh toán này?
Cân nhắc rủi ro, uy tín gian lận và phán quyết bot trước khi bạn ủy quyền thẻ.
Chấp nhận lượt đăng ký này?
Bắt tài khoản dùng một lần trước khi nó kịp tồn tại — đa tài khoản và uy tín có sức nặng lớn nhất ở đây.
Cho vào?
Tự động siết chặt khi bộ phát hiện chiếm đoạt tài khoản đã kích hoạt trên lượt truy cập đó.
Tính chuyển đổi này?
Tách một lượt giới thiệu thật khỏi việc tự giới thiệu chính mình hoặc một con bot được trả thưởng.
Một bộ từ vựng bốn từ
Mỗi kịch bản nhận một trong bốn câu trả lời, và đi kèm là căn cứ đã dẫn tới nó — những trục quyết định lấy từ một bộ từ vựng cố định: bot, rủi ro, uy tín gian lận, hành vi, đa tài khoản, chiếm đoạt tài khoản, mạng, mẫu hình affiliate. Bạn luôn biết trục nào đã làm lời khuyên dịch chuyển, mà không bao giờ phải nhìn thấy tên tín hiệu, trọng số hay ngưỡng.
Một phép tính, ba kênh
Cùng một khối Guidance đi theo webhook, trả lời trong Data API và hiển thị trên thẻ khách truy cập trong dashboard — một bộ quy tắc, một kết quả, không phải đối soát gì ở phía bạn. Hãy đọc lời khuyên cho kịch bản của bạn thay vì lời khuyên tổng thể: tổng thể chỉ đơn giản là cái nghiêm ngặt nhất trong bốn cái, một bản tóm tắt cho dashboard chứ không phải một quyết định thanh toán. Phiên bản quy tắc được gửi kèm trong payload, nên việc quy tắc thay đổi là điều bạn nhìn thấy, chứ không phải điều bạn phải suy ra từ một lời khuyên bỗng dịch chuyển.
"guidance": { "version": 1, "overall": "review", "payment": "review", "registration": "challenge", "login": "allow", "affiliate": "allow", "basis": ["risk", "fraud_reputation"]}Năm SDK ở phía front end, hai kênh ở phía back end
Phía trình duyệt được phát hành dưới dạng năm SDK — JavaScript thuần, React, Vue 3, Angular và Svelte 5. Không có SDK phía máy chủ, và đó là chủ đích: backend của bạn tích hợp qua HTTP thuần thông qua webhook có chữ ký và Data API. Việc xác minh chữ ký chỉ tốn chừng một chục dòng đối chiếu với vector tham chiếu mà chúng tôi công bố, và không có thứ gì thêm phải liên tục nâng cấp trong cây phụ thuộc máy chủ của bạn.
Câu hỏi thường gặp
Đấu nối xong trong một buổi chiều
Tạo một webhook trong dashboard, trỏ nó tới endpoint của bạn rồi bấm Test. Xác minh chữ ký đối chiếu với vector tham chiếu của chúng tôi, và phần khó nhất đã ở lại phía sau.