快速入门

本指南将帮助你在几分钟内将 Noxtica 添加到你的 Web 应用中。

前提条件

一个 Noxtica 账户（通过联系我们申请访问权限）
你的站点密钥（账户创建后提供）

快速集成

账户创建好且你已获得站点密钥后，将我们的采集器添加到你的 HTML 中——安装就这么简单。

自动采集（推荐）

集成 Noxtica 最简单的方式是使用运行一次模式：

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

这将：

在首次访问时对访客进行评估
在缓存有效期内（默认：7 天）对回访复用已缓存的结果
悄悄记录回访，无需重新执行完整评估
跨已打开的标签页协调，确保访客只被评估一次

结果可通过以下方式获取：

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

手动采集

如需更精细的控制，使用 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>

使用 `checkOnce()` 进行智能采集

想要最小的资源占用，请使用 checkOnce()——它会遵守你在服务端配置的采集间隔，这样访客不会被重复评估超过必要的次数：

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

性能与页面影响

采集器的设计将对页面加载和用户可感知延迟的影响降至最低：

指标	数值
初始脚本大小	~167 KB（压缩前），~55 KB（brotli 压缩后）
采集时间（中位数，首次）	现代桌面 <50ms / 中档手机 <120ms
风险评分响应时间	中位数 <150ms（采集器边缘 → API 边缘）
缓存访问（首次加载后）	<10ms（无指纹工作；仅一次信标）
主线程阻塞	无 — 采集以异步块的方式运行

我们如何保持轻量：

async 脚本属性 — 采集器在后台加载，绝不延迟你的页面变为可见或可交互状态。
运行一次模式（data-auto-check-once） — 首次评估后，缓存有效期内的回访只发送一个极小的访问信标（约 150 字节）。
跨标签页协调 — 多个已打开的标签页合并为一次评估。
首次加载后缓存 — 防篡改的 KHAN VM 会被浏览器缓存，后续访问瞬间加载。
后台处理（在支持的情况下），让工作远离主线程，保持你的页面响应流畅。

如果添加 SDK 后发现速度变慢，使用 await client.collectAndSubmit({ telemetry: true }) 抓取一个性能分析——返回的 result.telemetry 包含详细的时间分解。

沙盒环境与生产环境

你会有两个站点密钥：一个用于开发和预发环境，一个用于生产环境。每个密钥在其自己的策略下运行，数据完全隔离。

方面	沙盒（`pk_sand_*`）	生产（`pk_prod_*`）
站点密钥前缀	`pk_sand_`	`pk_prod_`
来源白名单	本地 + 你的预发来源	严格——仅限你已注册的来源
速率限制	宽松（约 1000/分钟/IP）	按套餐限制执行
风险评分策略	宽松——最少的机器人拦截	应用生产策略
数据保留	7 天	按租户配置（默认 90 天）
审计日志保留	7 天	按租户配置（默认 90 天）
升级 MFA	可选	破坏性操作必须

请务必按环境切换站点密钥。 绝不要在生产流量中使用 pk_sand_* 密钥——沙盒数据不会出现在你的生产控制台，且风险评分会过于宽松。反之，在开发中使用 pk_prod_* 密钥会消耗生产速率限制配额。

一个常用的模式：

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

标签管理器兼容性

采集器可在 Google Tag Manager、Adobe Launch、Tealium 和 Segment 中运行，但有注意事项：

推荐（首选）： 直接在 HTML 中添加脚本，紧靠 </body> 之前或在 <head> 中带 async。尽早启动可以让采集器提前准备好，确保在访客产生交互时已就绪。

标签管理器——可用，但有注意事项：

✅ 大多数现代标签管理器（GTM 自定义 HTML、Adobe Launch 自定义代码、Segment 自定义来源）可以成功加载采集器。
⚠️ 阻止脚本直到访客接受同意的同意门控，会延迟首次评估——通常直到同意弹窗被关闭后才会运行任何东西。这是正确的行为；只需注意这可能影响你的”决策时间”指标。
⚠️ 某些旧版标签管理器会丢弃自定义 data-* 属性。如果 data-site-key 没有传到脚本标签，auto-init 就无法启动。可改用代码方式设置：
```
NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();
```
❌ 少数沙箱化程度很高的标签容器（罕见）会阻止防篡改运行时启动。SDK 会以轻量级采集模式继续工作，并在控制台输出警告。

如果必须通过标签管理器集成，请将 Noxtica 标签配置为在 All Pages — Window Loaded（或等效事件）时触发，而不是 DOM Ready——这样可以确保同意状态在任何内容运行之前已经确定。

内容安全策略

如果你的网站使用了内容安全策略，你需要允许 Noxtica 加载、运行其防篡改运行时（KHAN VM），并与我们的 API 通信。以下示例涵盖了所有这三点：

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

如果策略中缺少 'wasm-unsafe-eval' 标记，浏览器会阻止防篡改运行时，你会在控制台看到相关警告。Noxtica 继续工作——它会回退到轻量级采集模式——但防篡改保护会减弱。添加上述标记即可恢复完整体验。

站点密钥

你的站点密钥（pk_...）是对来自你的域名的请求进行身份验证的公开标识符。你在 Backoffice 中添加的每个域名都会获得唯一的站点密钥。

重要提示：

站点密钥是公开的，可以安全地嵌入到你的 HTML 中
每个站点密钥都绑定到特定来源（例如：https://example.com）
API 将拒绝来源与站点密钥注册域名不匹配的请求

配置选项

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

采集模式

模式	信号	最适合
`minimal`	小型核心信号集	最快采集，最小资源占用
`standard`	广泛的信号集	倾向于使用轻量信号集的网站
`max`	完整的信号集	最高精度（默认）

响应格式

采集并提交后，你将收到：

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

风险等级

分数	等级	含义
0-19	`minimal`	风险极低，大概率合法
20-39	`low`	风险较低，轻微异常
40-59	`medium`	中等风险，存在一些迹象
60-79	`high`	高风险，可能为自动化
80-100	`critical`	风险极高，已确认为机器人

身份验证

SDK 使用短效的、自动轮换的凭据对每次访问进行身份验证，这些凭据与你的站点密钥绑定。它会自动请求凭据、刷新凭据，并将其附加到每次提交中。

你无需管理这些——SDK 会自动处理一切。

接入流程

申请访问：联系我们申请演示或开始使用
账户创建：我们在平台中为你创建租户账户
添加域名：登录 Backoffice，进入 Domains，添加你的来源
复制站点密钥：每个域名都会获得唯一的站点密钥
集成：将带有站点密钥的脚本添加到你的页面
监控：在 Backoffice 控制台中查看指纹数据和分析

管理多个域名

Noxtica 支持每个账户管理多个域名：

生产环境：https://www.yoursite.com
预发环境：https://staging.yoursite.com
移动端：https://m.yoursite.com

每个域名都有自己的站点密钥。你可以：

在不重新生成密钥的情况下启用/禁用域名
若站点密钥泄露，可进行轮换
按域名筛选查看分析数据

SDK 版本

当前 SDK 版本：3.3.0（Schema：2026-05-24）

3.3.0 的新功能

轻量级行为信号（始终开启） — 简单的时序线索，例如会话持续时长以及访客首次交互的速度。无生物特征数据，无需终端用户同意。
行为生物特征（可选，需手动开启） — 当你在 Backoffice → 设置 → 行为生物特征中开启后，Noxtica 还会分析鼠标移动节奏、点击时序和滚动行为。依据严格的隐私法规，此功能属于生物特征数据，需要明确的终端用户同意。详见下方行为生物特征。
Apple Pay 一致性检查 — 确认声称是 iPhone 的设备确实表现得像一台 iPhone，从而捕获一种常见的伪装手法。
网络指纹匹配 — 识别常见自动化工具的特征性连接模式，让来自脚本和机器人的流量即便在浏览器看起来很可信的情况下也能显露出来。
IP 声誉 — 对来自声誉不佳网络的访客进行标记，并支持接入你自己偏好的威胁情报服务。

行为生物特征（可选，需手动开启）

Noxtica 还可以分析某人移动鼠标、点击和滚动的节奏。这是一个需要手动开启的功能，默认关闭。

为什么需要手动开启？ 此类行为数据依据严格的隐私法规属于敏感个人数据，因此采集时需要你的终端用户的明确同意。我们将其设为手动开启，让你掌控何时以及如何使用它。

如何开启：

登录 Backoffice → 设置 → 行为生物特征
与你的隐私或法律团队一同审阅合规说明
更新你的隐私政策和同意横幅，披露此项采集
开启该功能

开启后，Noxtica 会自动将这些行为信号纳入后续评估，你的控制台会显示每个域名对应的行为评分。

后续步骤

试用在线演示，亲眼看看指纹识别效果
阅读后端集成指南，了解服务端查询
访问控制台查看已采集的数据

快速入门

前提条件

快速集成

自动采集（推荐）

手动采集

使用 checkOnce() 进行智能采集

性能与页面影响

沙盒环境与生产环境

标签管理器兼容性

内容安全策略

站点密钥

配置选项

采集模式

响应格式

风险等级

身份验证

接入流程

管理多个域名

SDK 版本

3.3.0 的新功能

行为生物特征（可选，需手动开启）

后续步骤

使用 `checkOnce()` 进行智能采集