浏览器运行时

本指南说明 Noxtica SDK 在访客浏览器中的工作方式——评估过程中发生了什么、缓存如何让速度保持快速，以及如何排查常见问题。

工作原理

当你在页面中引入 Noxtica SDK 时，它会悄悄做四件事：

1. 认证：使用它为你管理的凭据，以你的站点密钥完成登录
2. 采集：读取浏览器本就会暴露的日常信号
3. 提交：将信号发送至 Noxtica 进行评分
4. 缓存：将结果缓存在本地，避免每次访问都重复这些工作

整个过程在后台运行，绝不阻塞你的页面。

采集流程

自动（推荐）

使用 data-auto-check-once 时，SDK 采用智能采集策略：

<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>

使用了内容安全策略（CSP）？ 你需要允许 Noxtica 加载并运行其防篡改运行时 KHAN VM。如果无法启动，Noxtica 会以轻量模式继续工作，但防篡改保护会减弱。详见 快速入门 → 内容安全策略。

首次访问：执行完整评估并缓存结果。

后续访问（缓存有效期内）：返回已缓存的结果，并记录一次轻量级访问，不再执行重量级工作。

缓存过期后：重新执行完整评估。

手动控制

如需以编程方式控制，请使用 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');
}

缓存行为

SDK 将每次结果缓存在浏览器中，避免对同一访客在每次页面浏览时都重新评估。

缓存键

nox_fp_{your_site_key}

缓存内容

• 设备 ID
• 上次提交的时间戳
• 上次出现的时间戳
• 之前的风险评分与等级

TTL（有效期）

默认缓存 TTL 为 7 天，可进行配置：

// 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
});

强制刷新

要绕过缓存并采集新的指纹：

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

跨标签页协调

当访客同时打开你网站的多个标签页时，SDK 会确保只评估一次：

• 只有一个标签页执行实际工作
• 其他标签页等待并共享该结果

这一切自动进行——无需任何配置。

事件

SDK 会派发你可以监听的事件：

noxtica:collected

在采集成功或返回缓存结果后触发：

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

专门在返回缓存结果时触发：

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

noxtica:error

在采集失败时触发：

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

全局变量

采集完成后，结果可通过全局变量访问：

// 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);

错误处理

常见错误

手动处理错误

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
	}
}

采集模式

SDK 支持三种采集模式：

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

保护模式（KHAN VM）

与机器人对抗最难的地方在于，浏览器中运行的任何东西原则上都是可见、可编辑的。有心的攻击者可以读取页面代码，弄清楚在测量什么，然后悄悄地反馈虚假的答案。

KHAN VM 拉高了这个代价。Noxtica 不是把采集逻辑以可读代码的形式摆在页面上，而是将敏感部分运行在一个密封的沙盒运行时中。决定测量什么的逻辑不再一目了然，攻击者无法轻易研究和改写；它产生的结果在离开浏览器之前就被密封——因此篡改或重放要困难得多。

KHAN VM 能帮助实现：

• 防篡改的评估结果 — 评估在发送前已在沙盒内密封，页面上的其他脚本无法悄悄修改或重放它。
• 更难被逆向工程 — 采集逻辑隐藏在运行时内部，而不是以可读形式暴露在浏览器开发者工具中。
• 重放保护 — 每次结果都是一次性的且经过验证，捕获的响应无法被简单复用来伪造干净的访客。

诚实的限制——它不能做到：

• 这是一个防篡改功能，不是端到端加密。
• 如果你自己的页面已被攻破（例如存在跨站脚本漏洞），页面上的攻击者能看到与 Noxtica 相同的原始浏览器信号。KHAN VM 保护的是处理过程和结果，而不是围绕它的页面环境。

KHAN VM 从服务端开启，无需对你的集成做任何修改。如果无法启动——例如内容安全策略将其阻止——Noxtica 会回退到轻量级采集模式，确保检测继续运行，只是防篡改保护会减弱。

浏览器支持

SDK 支持现代浏览器：

较旧的浏览器可能信号精度降低，但仍能正常工作。

调试模式

启用调试日志以排查问题：

// 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>;

调试模式会记录：

• 采集进度
• Token 生命周期
• 缓存命中与未命中
• 遇到的任何错误

注意：调试模式在生产环境中默认静默。除非明确启用，否则不会有控制台输出。

存储相关注意事项

浏览器存储

SDK 使用浏览器的本地存储（localStorage）缓存结果。如果不可用（例如在隐私浏览模式下，或存储被禁用时）：

• 检测仍然正常工作
• 每次页面加载都会执行新的评估
• 跨标签页协调可能减弱

不使用 Cookie

SDK 不使用 Cookie。它需要的所有数据都保存在浏览器的本地存储中。

性能影响

首次访问

采集异步运行，不会阻塞页面渲染。

后续访问（缓存命中）

故障排查

未采集到指纹

1. 检查浏览器控制台是否有错误
2. 确认站点密钥与你的域名完全匹配（包括 https://）
3. 确保该域名已在 Backoffice 中启用
4. 开启调试模式查看详细日志

”WebAssembly blocked by Content Security Policy”

如果你在浏览器控制台看到此警告，说明你页面的内容安全策略阻止了防篡改运行时（KHAN VM）。检测会继续以轻量模式工作，但开启它可以获得最强的保护。

使用以下配置允许 Noxtica 加载和运行：

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

详见快速入门 → 内容安全策略。

同一设备上出现不同的设备 ID

以下情况可能导致这种现象：

• 浏览器的已存储数据被清除
• 浏览器配置文件发生变化
• 访客使用了隐私/无痕浏览模式
• 浏览器经历了重大版本更新

这是预期行为——识别机制会随设备随时间的变化而自适应。

采集耗时过长

1. 检查网络面板中 API 响应是否较慢
2. 考虑使用 mode: 'minimal' 以加快采集
3. 确保 SDK 以 async 属性加载

事件未触发

1. 确保你在 SDK 运行之前就开始监听
2. 检查 auto-init 属性是否正确
3. 确认没有 JavaScript 错误阻塞执行

最佳实践

1. 使用 data-auto-check-once 而非 data-auto-collect，以减少不必要的重复采集

2. 以异步方式加载 SDK（使用 async 属性），避免阻塞页面加载

3. 监听事件，而不是轮询 window.noxticaResult

4. 不要随意修改 TTL——默认的 7 天间隔已针对大多数使用场景做了优化

5. 优雅处理错误——采集失败不应影响你的页面正常使用

后续步骤

• 快速入门 - 初始设置指南
• 后端集成 - 服务端设备查询