Browser Runtime

Hướng dẫn này giải thích cách Noxtica SDK vận hành bên trong trình duyệt của khách truy cập — những gì xảy ra trong quá trình đánh giá, cách lưu cache giữ cho mọi thứ nhanh chóng, và cách xử lý các sự cố thường gặp.

Cách hoạt động

Khi bạn thêm Noxtica SDK vào trang, nó lặng lẽ thực hiện bốn việc:

1. Xác thực: Đăng nhập bằng Site Key của bạn sử dụng thông tin xác thực mà nó tự quản lý
2. Thu thập: Đọc các tín hiệu thông thường mà trình duyệt vốn đã hiển thị
3. Gửi: Gửi chúng đến Noxtica để chấm điểm
4. Cache: Lưu kết quả cục bộ để không phải lặp lại công việc trong mỗi lượt truy cập

Tất cả điều này chạy ở nền và không bao giờ chặn trang của bạn.

Luồng thu thập

Tự động (Khuyến nghị)

Khi dùng data-auto-check-once, SDK sử dụng cơ chế thu thập thông minh:

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

Đang dùng content-security-policy? Bạn cần cho phép Noxtica tải và chạy môi trường chạy chống giả mạo của nó, KHAN VM. Nếu không thể, Noxtica tiếp tục hoạt động với hình thức thu thập nhẹ hơn và bảo vệ chống giả mạo yếu hơn. Xem Bắt Đầu → Content Security Policy để có đoạn code chính xác.

Lượt truy cập đầu tiên: Chạy đánh giá đầy đủ và lưu kết quả vào cache.

Các lượt truy cập tiếp theo (trong cửa sổ cache): Trả về kết quả đã cache và ghi lại một lượt truy cập nhẹ. Không chạy công việc nặng.

Sau khi cửa sổ cache hết hạn: Chạy đánh giá mới.

Điều khiển thủ công

Để kiểm soát theo lập trình, dùng phương thức checkOnce():

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

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

Hành vi cache

SDK lưu cache mỗi kết quả trong trình duyệt để không đánh giá lại cùng một khách truy cập trong mỗi lần xem trang.

Cache Key

nox_fp_{your_site_key}

Những gì được cache

• Device ID
• Thời điểm gửi gần nhất
• Thời điểm thấy gần nhất
• Điểm và mức rủi ro trước đó

TTL (Thời gian sống)

TTL cache mặc định là 7 ngày. Có thể cấu hình:

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

Buộc làm mới

Để bỏ qua cache và thu thập dấu vân tay mới:

const result = await client.checkOnce({
	forceRefresh: true,
});

Phối hợp giữa các tab

Khi khách truy cập mở nhiều tab của trang cùng lúc, SDK đảm bảo chỉ đánh giá họ một lần:

• Chỉ một tab thực hiện công việc thực
• Các tab còn lại chờ và dùng chung kết quả đó

Điều này diễn ra tự động — không cần cấu hình.

Sự kiện

SDK phát ra các sự kiện mà bạn có thể lắng nghe:

noxtica:collected

Phát ra sau khi thu thập thành công hoặc khi trả về kết quả đã cache:

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

Phát ra cụ thể khi trả về kết quả đã cache:

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

Phát ra khi thu thập thất bại:

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

Biến toàn cục

Sau khi thu thập, kết quả có sẵn ở phạm vi toàn cục:

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

Xử lý lỗi

Các lỗi thường gặp

Xử lý lỗi thủ công

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

Chế độ thu thập

SDK hỗ trợ ba chế độ thu thập:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // or 'minimal', 'standard'
});

Chế độ bảo vệ (KHAN VM)

Phần khó nhất trong việc chống bot là bất cứ thứ gì chạy trong trình duyệt, về nguyên tắc, đều có thể nhìn thấy và chỉnh sửa được. Một kẻ tấn công có quyết tâm có thể đọc code của trang, tìm hiểu những gì đang được đo lường, và lặng lẽ đưa vào những câu trả lời giả.

KHAN VM tăng chi phí của điều đó. Thay vì để lộ phần thu thập dưới dạng code có thể đọc được trên trang, Noxtica chạy phần nhạy cảm bên trong một môi trường chạy niêm phong, cách ly. Logic quyết định những gì cần đo lường không nằm công khai để kẻ tấn công nghiên cứu và viết lại, và kết quả nó tạo ra được niêm phong trước khi rời khỏi trình duyệt — vì vậy rất khó để can thiệp hoặc phát lại.

Những gì KHAN VM giúp ích:

• Kết quả chống giả mạo — quá trình đánh giá được niêm phong bên trong sandbox trước khi gửi đi, vì vậy các script khác trên trang không thể lặng lẽ thay đổi hoặc phát lại nó.
• Khó phân tích ngược hơn — logic thu thập vẫn ẩn bên trong môi trường chạy thay vì có thể đọc trong công cụ developer của trình duyệt.
• Bảo vệ phát lại — mỗi kết quả dùng một lần và được xác minh, vì vậy phản hồi đã bắt được không thể đơn giản tái sử dụng để giả mạo khách truy cập sạch.

Giới hạn thực tế — những gì nó không làm:

• Đây là tính năng chống giả mạo, không phải mã hóa đầu-cuối.
• Nếu trang của bạn bị xâm phạm (ví dụ: lỗi cross-site scripting), một kẻ tấn công trên trang đó có thể thấy cùng các tín hiệu trình duyệt thô mà Noxtica thấy. KHAN VM bảo vệ quá trình xử lý và kết quả, không phải trang xung quanh nó.

KHAN VM được bật từ phía server và không cần thay đổi gì trong tích hợp của bạn. Nếu nó không thể khởi động — ví dụ vì content-security-policy chặn nó — Noxtica chuyển về hình thức thu thập nhẹ hơn để phát hiện tiếp tục hoạt động, chỉ với bảo vệ chống giả mạo yếu hơn.

Hỗ trợ trình duyệt

SDK hỗ trợ các trình duyệt hiện đại:

Các trình duyệt cũ hơn có thể có độ chính xác tín hiệu thấp hơn nhưng vẫn hoạt động.

Chế độ Debug

Bật ghi nhật ký debug để xử lý sự cố:

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

Chế độ debug ghi lại:

• Tiến trình thu thập
• Vòng đời token
• Cache hit và miss
• Các lỗi gặp phải

Lưu ý: Chế độ debug im lặng theo mặc định trong môi trường production. Không có đầu ra console nào hiện ra trừ khi được bật rõ ràng.

Vấn đề về lưu trữ

Bộ nhớ trình duyệt

SDK dùng bộ nhớ cục bộ của trình duyệt để lưu cache kết quả. Nếu không có sẵn (ví dụ: trong chế độ duyệt ẩn hoặc khi tắt lưu trữ):

• Phát hiện vẫn hoạt động
• Mỗi lần tải trang chạy đánh giá mới
• Phối hợp giữa các tab có thể bị giảm

Không dùng Cookies

SDK không dùng cookies. Mọi thứ nó cần được giữ trong bộ nhớ cục bộ của trình duyệt.

Tác động hiệu năng

Lượt truy cập đầu tiên

Thu thập chạy bất đồng bộ và không chặn render trang.

Các lượt truy cập tiếp theo (Cache Hit)

Xử lý sự cố

Dấu vân tay không được thu thập

1. Kiểm tra console trình duyệt xem có lỗi không
2. Xác minh Site Key khớp chính xác với domain (kể cả https://)
3. Đảm bảo domain đang được bật trong Backoffice
4. Bật chế độ debug để xem nhật ký chi tiết

”WebAssembly blocked by Content Security Policy”

Nếu bạn thấy cảnh báo này trong console trình duyệt, content-security-policy của trang đang chặn môi trường chạy chống giả mạo (KHAN VM). Phát hiện tiếp tục hoạt động ở chế độ nhẹ hơn, nhưng bạn sẽ có bảo vệ mạnh nhất bằng cách cho phép nó.

Dùng đoạn code bên dưới để cho phép Noxtica tải và chạy:

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

Xem Bắt Đầu → Content Security Policy để có tài liệu tham khảo đầy đủ.

Device ID khác nhau trên cùng một thiết bị

Điều này có thể xảy ra khi:

• Dữ liệu lưu trữ của trình duyệt bị xóa
• Profile trình duyệt thay đổi
• Khách truy cập dùng chế độ riêng tư/ẩn danh
• Trình duyệt trải qua cập nhật lớn

Đây là hành vi bình thường — việc nhận dạng thích nghi khi thiết bị thay đổi theo thời gian.

Thu thập mất quá lâu

1. Kiểm tra tab mạng xem phản hồi API có chậm không
2. Cân nhắc dùng mode: 'minimal' để thu thập nhanh hơn
3. Đảm bảo SDK được tải với thuộc tính async

Sự kiện không được phát

1. Đảm bảo bạn lắng nghe trước khi SDK chạy
2. Kiểm tra các thuộc tính auto-init có đúng không
3. Xác minh không có lỗi JavaScript nào chặn việc thực thi

Các thực hành tốt nhất

1. Dùng data-auto-check-once thay vì data-auto-collect để giảm thiểu thu thập trùng lặp

2. Tải SDK bất đồng bộ với thuộc tính async để tránh chặn tải trang

3. Lắng nghe sự kiện thay vì polling window.noxticaResult

4. Đừng ghi đè TTL không cần thiết — khoảng 7 ngày mặc định đã được tối ưu cho hầu hết trường hợp

5. Xử lý lỗi nhẹ nhàng — thu thập thất bại không nên làm hỏng trang của bạn

Bước tiếp theo

• Bắt Đầu — Hướng dẫn thiết lập ban đầu
• Tích hợp Backend — Tra cứu thiết bị phía server