EchoScan Browser Verifier

中文 | English

中文

EchoScan Browser Verifier 提供浏览器侧指纹采集入口。公开调用方式为 createEchoScan().run()，返回 imprint。

报告查询与最终风险判定由服务端执行，不在前端执行。

安装

npm install @echoscan/browser-verifier

本地完整服务启动（免手动 set 环境变量）

1. 在仓库根目录复制配置模板：

cp .env.local.example .env.local

2. 在 .env.local 中填入你的 ECHOSCAN_SITE_BFF_SERVICE_KEY

3. 直接启动：

npm run dev:full

说明：dev:full / dev:site 会自动加载 .env.local 与 .env.development.local（仅在变量未设置时注入），所以本地只需一次配置即可。

最简接入

import { createEchoScan } from '@echoscan/browser-verifier';

const verifier = createEchoScan();
const { imprint } = await verifier.run();

返回示例：

{
  "imprint": "fp_session_17739000000000000"
}

ESM / UMD 使用

ESM（npm）：

import { createEchoScan } from '@echoscan/browser-verifier';

const verifier = createEchoScan();
const { imprint } = await verifier.run();

ESM（CDN）：

<script type="module">
  import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js';
  const verifier = createEchoScan();
  const { imprint } = await verifier.run();
  console.log(imprint);
</script>

UMD（script）：

<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
  const verifier = window.EchoScan.createEchoScan();
  verifier.run().then(({ imprint }) => console.log(imprint));
</script>

自托管说明

如果你将 SDK 文件托管到自有 CDN 或对象存储，请确保同版本依赖文件可被浏览器访问，避免模块加载失败（例如分块文件 404）。

服务端对接

浏览器端拿到 imprint 后，应发送到你的服务端，由服务端继续完成报告查询与业务判定。

服务端返回值与错误参考：

• https://github.com/ozzxzzo/fingerprint-system/blob/master/echoscan/docs/SERVER_API_REFERENCE.md

示例（最小流程）：

// browser
const { imprint } = await verifier.run();
await fetch('/api/verify-imprint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ imprint }),
});

// your backend (example)
app.post('/api/verify-imprint', async (req, res) => {
  const { imprint } = req.body;
  // query EchoScan report in backend and make your business decision
  // const report = await ...
  res.json({ ok: true });
});

English

EchoScan Browser Verifier provides browser-side fingerprint collection. Its public callable entrypoint is createEchoScan().run(), returning imprint.

Report queries and final risk decisions are server-side responsibilities.

Install

npm install @echoscan/browser-verifier

Minimal usage

import { createEchoScan } from '@echoscan/browser-verifier';

const verifier = createEchoScan();
const { imprint } = await verifier.run();

Example response:

{
  "imprint": "fp_session_17739000000000000"
}

ESM / UMD usage

ESM (npm):

import { createEchoScan } from '@echoscan/browser-verifier';

const verifier = createEchoScan();
const { imprint } = await verifier.run();

ESM (CDN):

<script type="module">
  import { createEchoScan } from 'https://cdn.echoscan.org/v1/echoscan.esm.js';
  const verifier = createEchoScan();
  const { imprint } = await verifier.run();
  console.log(imprint);
</script>

UMD (script):

<script src="https://cdn.echoscan.org/v1/echoscan.umd.js"></script>
<script>
  const verifier = window.EchoScan.createEchoScan();
  verifier.run().then(({ imprint }) => console.log(imprint));
</script>

Self-hosting note

If you host SDK files on your own CDN/object storage, make sure all same-version dependent files are publicly reachable to avoid module loading failures (for example, chunk 404 errors).

Server integration

After you receive imprint in browser, send it to your backend. Your backend should perform report queries and decision logic.

Server response/error reference:

• https://github.com/ozzxzzo/fingerprint-system/blob/master/echoscan/docs/SERVER_API_REFERENCE.md

Example (minimal flow):

// browser
const { imprint } = await verifier.run();
await fetch('/api/verify-imprint', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ imprint }),
});

// your backend (example)
app.post('/api/verify-imprint', async (req, res) => {
  const { imprint } = req.body;
  // query EchoScan report in backend and make your business decision
  // const report = await ...
  res.json({ ok: true });
});