ACCUZ® Brand Guard™ / SDK 1.3.3 / HTTP API v1

客户网站接入指南

从这里开始

网站后端与浏览器分工

标签打开已批准的官网入口。在代理改写或页面重定向前取得完整 HTTPS 地址,保留大小写、参数顺序和百分号编码。让受信任代理保留原始域名和请求目标。日志中省略完整碰卡网址、原始 IP 和认证头。

Token 仅保存在网站后端的秘密存储中,由后端调用分配的验真 API。浏览器只收到与本会话绑定的临时结果引用。结果使用 Cache-Control: no-store 和 no-referrer 策略,分析工具不收集 Cookie 或幂等键。

提交和恢复同一笔验真

首次 POST 前,用事务保存随机幂等键、完整请求正文、已分配 API 地址、编码与选页配置。向 POST /api/customer/v1/verifications 发送 Authorization: Bearer …、Content-Type: application/json 和 Idempotency-Key。正文必填 encodingVersionId、tapUrl,可选 clientRequestId 用于关联诊断。原始网址最长 1024 个 UTF-8 字节,整个正文最多 4096 字节。

丢失响应或收到 HTTP 202、429、503 时,保留原地址、键及正文,遵循 Retry-After,在操作有效期内恢复。未决操作的处理租约到期后,用原 POST 继续。GET /api/customer/v1/verifications/{verificationId} 需 verifications:read,只读取已有操作。仅有 verifications:execute 的后端用原 POST 恢复。一次新的实物碰卡开始一笔新操作。

完整收到 HTTP 200 后,如正文不可解析、必填时间无效、身份不可信、封签字段矛盾或编码 ID 不匹配,本次操作以“未确认”结束。保留安全的排查编号与错误类别,清理原始碰卡数据并停止自动重试。分别验证 acceptedAt 和 decidedAt;有效回执允许两者取值不同。可选选页信息缺失或异常时,在通用页显示可信的原判定。

接入自有后端

从服务端引入 helper,传入已核实的分配参数。下面的 operation 是首次请求前已持久化的操作,originalUrl 是原始读取地址,token 来自服务器秘密存储。先保存已确认的回执,再让浏览器进入结果页面。可运行适配器提供事务、并发和结果未确认时的处理示例。

import { verifyTap } from './reference/verification-core.mjs';

const result = await verifyTap({
  baseUrl: operation.apiOrigin,
  approvedApiOrigin: settings.apiOrigin,
  originalApiOrigin: operation.apiOrigin,
  encodingVersionId: operation.encodingVersionId,
  tapUrl: operation.originalUrl,
  idempotencyKey: operation.idempotencyKey,
  token
});

根据已判定的回执选择商品页

先看 receipt.result。本次为 valid 且当前有资格时才选商品页。已确认的单件专属路径优先。SKU 模式按完整 SKU 精确查询网站目录,保留大小写和标点,由网站决定语言和相应网址。路径模式只采用核准的同源站内地址。UID 模式从受控后端查找已登记的关联,建立或变更关联由获授权的业务流程完成。

SKU 缺失、格式异常、目标路径不安全或未知型号时,基础验真结果仍应在通用页如实显示。网站若已有经确认的单件映射,可在租户和已验出单件均匹配时使用。首次接入无需导入单件清单。单独打开商品页也不能产生新碰卡。

官网按 SKU 选页时,在服务端为该商品登记允许的各语言同源路径。新碰卡按入口请求的 Accept-Language 或默认语言选取已登记页。访客手动切换语言时,应在本站内传递不透明回执引用。只允许该次验出的商品已冻结的路径展示回执;单件专属页优先。

嵌入现有商品页

在产品页模板加载模块并放入组件。同源提供 /bg/component.mjs、/bg/result、/bg/retry 和 /bg/presented,保留 /v/result 与各条已批准的 NFC 入口。保留产品页本身的业务查询参数;__bg_receipt 为绑定浏览器会话的展示引用。

组件显示原判定时间及本次适用的接受次数、封签证据。本次碰卡首次确认可能来自原键恢复;再次打开或刷新已展示结果时,显示上次回执。当前资格变动时,分开展示历史判定和当前状态。组件语言可随产品页模板选择。

组件内置英文、中文、日文和韩文,由模板的 lang 选择。需要其他语言时,在模块加载之后、挂载组件之前调用 BrandGuardVerification.registerLocale(code, dictionary)。

组件显示回执后,会向同源的 /bg/presented 确认本次已展示。请保留整个 /bg/* 路由。首次结果响应丢失时,恢复后仍能正确显示为本次结果。

服务端交付原始带时区的判定时间,组件按当前页面语言与配置的展示时区格式化,展示时区默认 UTC。同一回执切换语言时保持同一时刻和次数。封签证据独立于验真判定;本次读取未报告开启,不能据此推断从未被打开。

<script type="module" src="/bg/component.mjs"></script>
<brandguard-verification lang="zh"></brandguard-verification>

运行参考适配器

新手从 config/site.example.json 开始:一条 entryPath /v、一个 encodingVersionId、一个服务端环境 secret BRANDGUARD_VERIFICATION_TOKEN。复制到私有且被忽略的 config/site.local.json,由服务器配置将 BG_SITE_CONFIG 指向该文件,在已批准的 HTTPS 来源后才运行 node reference/node-server.mjs --live。Token 不进入源码、浏览器或命令行参数。默认 node reference/node-server.mjs 是无需凭据的本机模拟。文件存储仅支持单进程。

Cloudflare 按 docs/cloudflare.html 和实际默认 wrangler.toml 操作:声明 SQLite Durable Object,接管 /v*、/v/result*、/bg/* 路由,并要求 SITE_CONFIG、BRANDGUARD_VERIFICATION_TOKEN 两个 secret。私密配置助手验证并生成秘密文件,不显示值。固定版本的 Wrangler 将代码和必需 secret 一起上传,缺少必需 secret 时部署失败。维护方只跑本地测试和 dry-run,不宣称实际部署。

运行 npm test 执行无依赖离线自测。完整测试及 Wrangler 使用 Node ≥22.12(已用 24.16 验证);Node 20 仅支持无依赖参考。安装 Node、npm,首次运行时可访问软件包仓库,然后用一条命令 npm run test:full 安装锁定的测试依赖并执行全部测试,其中包含原生 workerd/SQLite。默认报告写入解压目录内的 test-output/。如需其他位置,设置 BG_SDK_QA_DIR。

高级场景:只有确需不同已批准路径分别绑定编码与凭据时,才用 config/advanced-multi-entry.example.json 与 wrangler.advanced.toml。中性第二入口示例为 /scan/verify。兼容商品可共用默认单入口。改变路径可能需要匹配的已写标签;升级 SDK 不会改写标签。

能力与旧版升级

本包使用 HTTP API v1。SKU 与同源展示路径快照属于可选字段,取决于实体验出的单件、选页模式及平台能力。历史回执可能缺少两者。请按分配的环境向管理员核对支持情况。

从 1.2.3 或 1.3 升级时保留已写标签的准确入口和未决操作原环境。更换 SDK 本身不会轮换 Token、迁移租户或重写标签。原凭据是否沿用,以租户、连接、环境、有效期和权限一致为准。请为待测试标签核对编码 ID。使用同一获批编码的新型号可以复用该编码,改变入口或底层模板一般需要新的不可变编码。

普通 NTAG 424 DNA 提供标签认证;电子封签需要支持的芯片和编码。当 seal.supported 为 false 时明确显示“此标签不具备电子封签”,不要误报为封签读取缺失。采用新的准确路径时,核对写后 NDEF 读回及 iPhone 和 Android 的首条请求。

多个 SKU 可共用同一官网连接和兼容的编码。服务器在得到回执 SKU 之前就要选取凭据及编码。同一官网并行使用两条独立连接时,应能在收到碰卡时区分两者,例如给新连接配置官网、标签与 Writer 均支持的独立首跳路径,同时保留旧标签所需的配置。

从 1.3 / 1.3.1 升级时,检查自建重试队列与故障处理说明。旧接入可能在 401/403 后保留原请求供人工重投。1.3.3 参考流程在这两种情况下结束本次提交并清理敏感待处理数据。401 核对凭据缺失、过期、撤销及环境错误;403 核对连接是否启用、环境绑定及 execute/read 权限。修复后重新碰实体标签。已有受信任 verificationId 且具备读取权限时可查询原回执。传输不确定、202、429、503 继续用原操作和原键恢复。

可选地区信息

此功能默认关闭。启用前由管理员核对配置、告知与授权。只接受受控入口取得的访客 IP,排除服务器自身 IP 和未经验证的转发头。首次请求即固定可选上下文。仅在有数据时展示带归属标注的估算地区。地区是否可用不影响验真判定。

组件按页面语言展示可用的城市和国家信息;有国家代码时使用本地化名称,数据不可用时给出可读提示。不会展示来源代码、原因代码、坐标或 IP。显示地区估算或不可用提示时,均使用固定可点击的 DB-IP 和 CC BY 4.0 归属链接。

保存验收记录

对两件不同实物分别记录 SDK 和平台版本、verificationId、itemId、带时区的 decidedAt、判定、接受次数和实际落页。按需加上 SKU、选页方式和电子封签状态。覆盖另一款 SKU、缺映射、直接访问、刷新、原键恢复、新键重放、凭据撤销或缺权限以及跨浏览器访问。验证实际后端或 Worker。无凭据请求取得 401 可证明请求到达认证入口,成功的客户实卡回执仍需已分配参数和一次新碰卡。

分别记录三类验收。SDK 维护方验证 Node、原生 workerd/SQLite、多语、切页、多入口和错误凭据。客户工程师验证文档、契约、所获配置、真实官网和实卡。首次使用体验另请一位未参加此前联调的工程师从原 ZIP 开始操作,记录在哪一步需要帮助。

调整组件外观

组件为使用 Shadow DOM 的自定义元素。可继承字体和颜色,并通过 CSS ::part() 调整公开部件:heading、time、details、region、support、languages、language-link、attribution、provider-link、license-link、retry。无需改供应商 JavaScript 即可匹配官网字号、间距与链接颜色。保留判定、封签证据和归属链接;检查四语长文本与窄屏。

API 的可选回执字段为 visitorLocation,含 state、city、country、countryCode、source、unavailableReason、attribution。参考展示模型使用 location 与 regionEnabled。保留服务端快照;不接受访客自填地区,不从浏览器调用公共定位接口。组件按 countryCode 本地化国家名,不显示来源/原因代码或 IP。

brandguard-verification { font: inherit; color: #172923; }
brandguard-verification::part(heading) { font-size: 1.25rem; }
brandguard-verification::part(details) { font: inherit; white-space: pre-wrap; }
brandguard-verification::part(region) { margin-block: .75rem; }
brandguard-verification::part(languages) { display: flex; gap: .75rem; flex-wrap: wrap; }
brandguard-verification::part(language-link),
brandguard-verification::part(provider-link),
brandguard-verification::part(license-link) { color: #115e59; }

HTTP 错误码与验真判定 · OpenAPI v1