Bắt đầu

Hướng dẫn này sẽ giúp bạn thêm Noxtica vào ứng dụng web chỉ trong vài phút.

Yêu cầu trước khi bắt đầu

• Một tài khoản Noxtica (yêu cầu quyền truy cập qua liên hệ)
• Site Key của bạn (được cung cấp sau khi thiết lập tài khoản)

Tích hợp nhanh

Khi tài khoản đã sẵn sàng và bạn đã có Site Key, hãy thêm collector của chúng tôi vào HTML — đó là toàn bộ phần cài đặt.

Thu thập tự động (Khuyến nghị)

Cách đơn giản nhất để bắt đầu là để Noxtica tự chạy, sử dụng chế độ chạy một lần:

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key_here"
	data-auto-init
	data-auto-check-once
	async
></script>

Cách này sẽ:

• Đánh giá khách truy cập trong lần truy cập đầu tiên
• Tái sử dụng kết quả đó cho các lượt truy cập sau trong cửa sổ cache (mặc định: 7 ngày)
• Ghi lại các lượt truy cập quay lại một cách lặng lẽ mà không làm lại toàn bộ đánh giá
• Phối hợp giữa các tab đang mở để khách truy cập chỉ được đánh giá một lần

Kết quả có sẵn qua:

// Listen for results
document.addEventListener('noxtica:collected', function (e) {
	console.log('Fingerprint collected:', e.detail);
	console.log('Risk score:', e.detail.score);
	console.log('Risk level:', e.detail.risk_level);
});

// Or access directly after collection
console.log(window.noxticaResult);

Thu thập thủ công

Để kiểm soát chi tiết hơn, dùng JavaScript API:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Create a client with your Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Collect and submit in one call
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

Thu thập thông minh với checkOnce()

Để có dấu chân nhẹ nhất, dùng checkOnce() — nó tôn trọng khoảng thu thập bạn cấu hình trên server, để khách truy cập không bị đánh giá lại thường xuyên hơn cần thiết:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key_here',
});

// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);

Hiệu năng & Tác động đến trang

Collector được thiết kế để có tác động tối thiểu đến tải trang và độ trễ mà người dùng cảm nhận:

Cách chúng tôi giữ nhẹ:

• Thuộc tính async của script — collector tải ở nền và không bao giờ làm chậm trang của bạn trước khi hiển thị hoặc tương tác được.
• Chế độ chạy một lần (data-auto-check-once) — sau đánh giá đầu tiên, các lượt truy cập lặp lại trong cửa sổ cache chỉ gửi một ping truy cập nhỏ (~150 byte).
• Phối hợp giữa các tab — nhiều tab đang mở gộp thành một đánh giá duy nhất.
• Đã cache sau lần tải đầu — KHAN VM chống giả mạo được trình duyệt lưu cache, vì vậy nó tải tức thì trong các lượt truy cập sau.
• Xử lý ở nền khi được hỗ trợ, để công việc ở ngoài main thread và trang của bạn giữ phản hồi.

Nếu bạn nhận thấy chậm sau khi thêm SDK, hãy chụp hồ sơ với await client.collectAndSubmit({ telemetry: true }) — result.telemetry trả về bao gồm phân tích thời gian.

Sandbox và Production

Bạn sẽ có hai Site Key: một cho phát triển và staging, một cho production. Mỗi cái chạy theo chính sách riêng và giữ dữ liệu hoàn toàn tách biệt.

Luôn chuyển Site Key theo môi trường. Không bao giờ dùng key pk_sand_* trong lưu lượng production — dữ liệu sandbox sẽ không xuất hiện trong bảng điều khiển production của bạn và chấm điểm rủi ro sẽ quá dễ tính. Ngược lại, dùng key pk_prod_* trong phát triển sẽ tiêu tốn ngân sách giới hạn tốc độ production.

Một mẫu phổ biến:

<script>
	// Pick the key by hostname; fall back to sandbox in dev.
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica.js';
	s.async = true;
	s.dataset.siteKey = KEY;
	s.dataset.autoInit = '';
	s.dataset.autoCheckOnce = '';
	document.head.appendChild(s);
</script>

Tương thích với Tag Manager

Collector hoạt động trong Google Tag Manager, Adobe Launch, Tealium, và Segment, NHƯNG có lưu ý:

Khuyến nghị (ưa thích): thêm script trực tiếp vào HTML, ngay trước </body> hoặc trong <head> với async. Bắt đầu sớm nhất có thể cho collector khởi đầu tốt nhất, để nó sẵn sàng khi khách truy cập tương tác.

Tag manager — hoạt động, có lưu ý:

• ✅ Hầu hết tag manager hiện đại (GTM Custom HTML, Adobe Launch Custom Code, Segment Custom Source) tải collector thành công.
• ⚠️ Các cổng đồng ý chặn script cho đến khi khách truy cập chấp nhận sẽ làm chậm đánh giá đầu tiên — thường không có gì chạy cho đến khi banner đồng ý bị bỏ qua. Đây là hành vi đúng; chỉ cần biết nó có thể làm lệch các chỉ số “thời gian đến quyết định” của bạn.
• ⚠️ Một số tag manager cũ hơn bỏ các thuộc tính data-* tùy chỉnh. Nếu data-site-key không đến được thẻ script, auto-init sẽ không khởi động. Hãy thiết lập nó trong code thay thế:

  NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();

• ❌ Một số container tag bị sandbox nặng (hiếm) ngăn môi trường chạy chống giả mạo khởi động. SDK tiếp tục hoạt động với hình thức thu thập nhẹ hơn và ghi lại cảnh báo console.

Nếu bạn phải tích hợp qua tag manager, hãy cấu hình nó để kích hoạt thẻ Noxtica trên All Pages — Window Loaded (hoặc tương đương) thay vì DOM Ready — điều này đảm bảo trạng thái đồng ý là cuối cùng trước khi bất cứ thứ gì chạy.

Content Security Policy

Nếu trang của bạn dùng content-security-policy, bạn cần cho phép Noxtica tải, chạy môi trường chạy chống giả mạo (KHAN VM), và giao tiếp với API của chúng tôi. Ví dụ bên dưới bao gồm cả ba:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com;
  connect-src 'self' https://collect.noxtica.com;

Nếu chính sách thiếu token 'wasm-unsafe-eval', trình duyệt chặn môi trường chạy chống giả mạo và bạn sẽ thấy cảnh báo liên quan trong console. Noxtica tiếp tục hoạt động — nó chuyển về hình thức thu thập nhẹ hơn — nhưng với bảo vệ chống giả mạo yếu hơn. Thêm token trên sẽ phục hồi trải nghiệm đầy đủ.

Site Key

Site Key của bạn (pk_...) là định danh công khai xác thực các yêu cầu từ domain của bạn. Mỗi domain bạn thêm trong Backoffice nhận một Site Key duy nhất.

Lưu ý quan trọng:

• Site Key là công khai và có thể nhúng an toàn vào HTML của bạn
• Mỗi Site Key gắn với một origin cụ thể (ví dụ: https://example.com)
• API sẽ từ chối các yêu cầu mà origin không khớp với domain đã đăng ký của Site Key

Tùy chọn cấu hình

const client = NoxticaCollector.createClient({
	// Your Site Key (required)
	siteKey: 'pk_prod_your_site_key_here',

	// API endpoint (defaults to production)
	apiUrl: 'https://collect.noxtica.com',

	// Collection mode: 'max' (default), 'standard', or 'minimal'
	// Omit to use max mode (recommended)
	// mode: 'standard', // Uncomment to opt out of max-only signals
});

Chế độ thu thập

Định dạng phản hồi

Sau khi thu thập và gửi, bạn nhận được:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"flags": [],
	"details": {
		"summary": "Detected 0 risk indicator(s)."
	}
}

Mức rủi ro

Xác thực

SDK xác thực mỗi lượt truy cập bằng thông tin xác thực ngắn hạn, tự động xoay vòng, gắn với Site Key của bạn. Nó yêu cầu, làm mới, và đính kèm chúng vào mỗi bản gửi thay cho bạn.

Bạn không cần quản lý bất kỳ điều nào trong số này — SDK tự xử lý hoàn toàn.

Quy trình onboarding

1. Yêu cầu quyền truy cập: Liên hệ với chúng tôi để yêu cầu demo hoặc bắt đầu
2. Thiết lập tài khoản: Chúng tôi tạo tài khoản tenant của bạn trên nền tảng
3. Thêm domain: Đăng nhập vào Backoffice, vào Domains, và thêm các origin của bạn
4. Sao chép Site Key: Mỗi domain nhận một Site Key duy nhất
5. Tích hợp: Thêm script với Site Key của bạn vào các trang
6. Theo dõi: Xem dấu vân tay và phân tích trong bảng điều khiển Backoffice

Quản lý nhiều domain

Noxtica hỗ trợ nhiều domain trên một tài khoản:

• Production: https://www.yoursite.com
• Staging: https://staging.yoursite.com
• Mobile: https://m.yoursite.com

Mỗi domain có Site Key riêng. Bạn có thể:

• Bật/tắt domain mà không cần tạo lại key
• Xoay vòng Site Key nếu bị xâm phạm
• Xem phân tích được lọc theo domain

Phiên bản SDK

Phiên bản SDK hiện tại: 3.3.0 (Schema: 2026-05-24)

Mới trong 3.3.0

• Tín hiệu hành vi nhẹ (luôn bật) — các gợi ý thời gian đơn giản như thời gian phiên kéo dài bao lâu và khách truy cập tương tác lần đầu nhanh như thế nào. Không có dữ liệu sinh trắc học, và không cần đồng ý của người dùng cuối.
• Sinh trắc học hành vi (opt-in) — khi bạn bật trong Backoffice → Settings → Behavioral Biometrics, Noxtica cũng xem xét nhịp điệu chuyển động chuột, thời gian nhấp chuột, và cuộn. Điều này được tính là dữ liệu sinh trắc học theo quy định quyền riêng tư nghiêm ngặt, vì vậy cần có đồng ý rõ ràng từ người dùng cuối. Xem Sinh trắc học hành vi bên dưới.
• Kiểm tra nhất quán Apple Pay — xác nhận rằng thiết bị tự nhận là iPhone thực sự hoạt động như một iPhone, bắt được một thủ thuật giả mạo phổ biến.
• Khớp dấu vân tay mạng — nhận ra các mẫu kết nối đặc trưng của các công cụ tự động hóa phổ biến, để lưu lượng từ script và bot nổi bật ngay cả khi trình duyệt trông thuyết phục.
• Danh tiếng IP — gắn cờ các khách truy cập đến từ các mạng có danh tiếng kém, với tùy chọn kết nối nguồn thông tin mối đe dọa ưa thích của riêng bạn.

Sinh trắc học hành vi (Tùy chọn, Opt-In)

Noxtica cũng có thể nghiên cứu nhịp điệu của cách ai đó di chuyển chuột, nhấp, và cuộn. Đây là tính năng opt-in, tắt theo mặc định.

Tại sao opt-in? Loại dữ liệu hành vi này được tính là dữ liệu cá nhân nhạy cảm theo quy định quyền riêng tư nghiêm ngặt, vì vậy việc thu thập nó đòi hỏi đồng ý rõ ràng từ người dùng cuối. Chúng tôi để nó opt-in để bạn kiểm soát khi nào và cách nó được sử dụng.

Để bật:

1. Đăng nhập vào Backoffice → Settings → Behavioral Biometrics
2. Xem lại thông báo tuân thủ với đội quyền riêng tư hoặc pháp lý của bạn
3. Cập nhật chính sách quyền riêng tư và banner đồng ý để tiết lộ việc thu thập này
4. Bật tính năng

Sau khi bật, Noxtica tự động tính các tín hiệu hành vi này vào các đánh giá tương lai, và bảng điều khiển của bạn hiển thị điểm hành vi kết quả theo domain.

Bước tiếp theo

• Thử bản demo trực tiếp để xem lấy dấu vân tay hoạt động
• Đọc hướng dẫn Tích hợp Backend cho các tra cứu phía server
• Truy cập bảng điều khiển để khám phá dữ liệu đã thu thập