接口参考

SDK 接入指南 · JSON Schema

基础地址： https://api.arenza.ai/api/v1/events/collect/{public_install_id}。公开安装 ID 为 arz_pub_ 加 32 位小写十六进制字符，在 Portal → AI Integrations 中获取。它不是 Bearer 凭据。

使用 SDK 时，不需要手动调用这些接口。 init() 调用 /session；业务代码调用 track() 时，SDK 发送 /events 请求。本节供自行编写浏览器 HTTP 请求或排查问题时使用。后端上报请看服务端事件。

触发条件由你决定，例如预约确认、询价受理或试用激活。当前浏览器接口将这些行为记为同一种通用交互，内部名称为 cta_click，不区分自定义事件名。

标识来源

• arenza_visitor_id 标识访客。 SDK 生成并保存在网站 cookie 中。自行发送 HTTP 请求时，用 window.arenzaEvents.getVisitorId() 读取。同一访客复用此 ID，不要每次事件都重新生成。读取 ID 不会上报数据。
• X-Arenza-Delivery-Id 标识请求。 SDK 为每个逻辑请求生成 UUID，事件重试时复用该 UUID。自行发送请求时，先用 crypto.randomUUID() 生成并保存；相同请求重试时复用，不同请求另建。它不是访客 ID 或业务事件名，各接收模式的去重规则也不一定相同。

浏览器鉴权

安装 ID 可以公开。/session 签发绑定接入配置、访客和 Origin 的短期凭据，/events 校验该凭据。这不证明网站归属或业务完成。不要在网页中放置服务端 API Key；可信业务结果应由后端确认。

来源限制使用可选配置 reporting_origins。未配置时，其他合法 HTTPS 来源也能用公开安装 ID 创建会话。 配置后，不匹配的来源返回 403 origin_not_allowed；采集模式也允许所列主机的子域名。另一项配置 allowed_origins 限制跨域身份交换（/link 和 /redeem），不限制普通会话或事件上报。这些是接入配置字段，不是 ArenzaBilling.create() 参数；本指南不表示 Portal 已提供相应编辑界面。

1. 创建会话

POST /session → 200 OK

调用时机： 访客同意采集后、首次事件上报前，以及凭据过期后。SDK 的 init() 负责此请求，track() 发送前也会确认会话有效。此请求记录一次页面访问，不是业务事件。

请求头

• Origin：页面的合法 HTTPS 来源，由浏览器自动发送。若已配置 reporting_origins，还须满足该限制。
• Content-Type: application/json
• X-Arenza-Delivery-Id：新生成的 UUID，不用于其他请求。

JSON 请求体

{
  "arenza_visitor_id": "arz_v_aaaaaaaaaaaa",
  "consent": true,
  "url": "https://your-site.example/page"
}

• arenza_visitor_id 必填：arz_v_ 后跟 12–80 位字母、数字、_ 或 -。后续事件使用同一个 ID。
• consent 必填：必须为 true。获得分析采集同意后才加载 SDK。
• url 必填：绝对 HTTPS 页面地址，须与 Origin 请求头同源，最多 2,048 字符。只记录来源和路径，不将查询参数存为页面地址。
• source 和 referrer 是可选归因线索，不要包含个人信息。

响应

{
  "session_token": "<opaque short-lived token>",
  "expires_in": 900,
  "mode": "measurement"
}

另行批准的连接可返回 mode: "shadow"。保管好 session_token，它绑定此访客 ID 和来源，900 秒后过期。过期后可创建新会话，SDK 的 init() 负责创建或更新。

2. 上报交互

POST /events → 202 Accepted

调用时机： 业务代码确认所选条件已发生。例如，收到预约成功的响应后再发送，而不是一点击提交按钮就发送。SDK 的 track() 负责此请求，发送前须有有效会话。

请求头

• 与会话请求相同的 Origin 和 Content-Type: application/json。
• X-Arenza-Delivery-Id：为本次交互新建的 UUID。
• Authorization: Bearer <session_token>：使用 /session 返回的凭据。

JSON 请求体

{
  "arenza_visitor_id": "arz_v_aaaaaaaaaaaa"
}

arenza_visitor_id 必填，且须匹配会话。接口还接受可选的扁平 properties 对象，最多 20 个非敏感标量字段，序列化后不超过 4 KiB。这些字段不定义事件类型或已完成的转化，目前也不存为客户可见的事件标签。 不要发送表单值、邮箱、价格、cookie 或秘密。整个请求体不得超过 8 KiB。

采集模式响应

{ "accepted": true, "mode": "measurement" }

批准的 shadow 会话成功时还返回 receipt_id 和 duplicate。两种模式的 202 都不证明注册成功、付款完成或产生费用。

错误与验收

错误格式为 { "error": { "code": "…" } }：

• 401 invalid_session：凭据缺失、过期、被撤销，或凭据、访客、来源不匹配。
• 403 origin_not_allowed：来源格式错误、未获配置允许，或接入已停用。
• 404 not_found：安装 ID 不存在或连接不受支持。
• 422 invalid_input / invalid_url：请求体、访客 ID、UUID、同意状态或页面地址有误。
• 429 rate_limited：按响应的 Retry-After 请求头等待后重试。

浏览器自动发送真实 Origin。curl 可以填写任意 Origin 字符串，因此只能检查协议，不能证明网站已安装或同意流程正常。这两个接口都会记录采集数据；未经单独批准，不要向客户生产品牌发送模拟请求。 在真实网站验收同意流程，确认一次交互只有一次 /events 202，并检查按钮和表单行为没有改变。

Schema： sessionRequest、sessionResponse、eventRequest、eventResponse 位于 $defs 下。JSON Schema 描述请求和响应结构；服务端还校验 Origin、会话凭据、请求 UUID、请求体大小和敏感属性名。

停止采集

访客在网站隐私设置中关闭分析采集时：

1. 调用 window.arenzaEvents?.stop() 停止当前客户端。
2. 按设置时相同的路径（/）和域名，删除网站的 arenza_visitor_id cookie。
3. 关闭期间不再加载或初始化 SDK，同时取消同意流程中等待执行的初始化和事件回调。

stop() 只停止该客户端，不会删除 cookie 或更改网站的同意设置。访客再次同意后，请创建新客户端，不要复用已停止的实例。

curl 测试

需要 Bash、curl 和 uuidgen。替换安装 ID 和来源，再填入 SDK 的访客 ID。仅对获批测试品牌执行：这些请求会记录一次访问和一次事件。页面地址须与请求来源相同，并满足已配置的来源限制。会话请求成功后再复制凭据。

INSTALL_ID='arz_pub_YOUR_32_LOWERCASE_HEX_CHARACTERS'
ORIGIN='https://your-site.example'
read -r -s -p 'Visitor ID from your site: ' VISITOR_ID; echo

curl -sS "https://api.arenza.ai/api/v1/events/collect/$INSTALL_ID/session" \
  -H "Origin: $ORIGIN" -H 'Content-Type: application/json' \
  -H "X-Arenza-Delivery-Id: $(uuidgen)" \
  -d "{\"arenza_visitor_id\":\"$VISITOR_ID\",\"consent\":true,\"url\":\"$ORIGIN/page\"}"
# Copy session_token from the response:
read -r -s -p 'session_token: ' TOKEN; echo

curl -i -sS "https://api.arenza.ai/api/v1/events/collect/$INSTALL_ID/events" \
  -H "Origin: $ORIGIN" -H 'Content-Type: application/json' \
  -H "X-Arenza-Delivery-Id: $(uuidgen)" -H "Authorization: Bearer $TOKEN" \
  -d "{\"arenza_visitor_id\":\"$VISITOR_ID\"}"
unset VISITOR_ID TOKEN

服务端事件

服务端字段

请求地址：

POST https://api.arenza.ai/api/v1/billing-events/{website_install_id}

使用 API Key 鉴权时，arz_pub_… 安装 ID 用来定位该品牌已配置的连接。已有的连接 UUID 仍然可用。不要把 API Key 放进 URL。

必需的请求头：Authorization: Bearer <API_KEY>、Content-Type: application/json 和 webhook-id: <delivery UUID>。使用 Bearer 时，不需要 HMAC 签名或签名时间戳。

向 Arenza 上报时，访客 ID 应放在 attribution.visitor_id 中，而不是顶层的 arenza_visitor_id。

JSON——测试事件示例；请替换为实际业务记录及已配置的事件类型。

{
  "spec_version": "1.0",
  "event_id": "booking-event-123",
  "event_handle": "YOUR_CONFIGURED_EVENT_HANDLE",
  "occurred_at": "2026-09-24T12:00:00Z",
  "subject": { "type": "booking", "id": "booking-123" },
  "attribution": { "visitor_id": "arz_v_aaaaaaaaaaaa" },
  "status": "test"
}

响应与错误

**HTML / JavaScript：**触发一次经批准的测试，在浏览器开发者工具的 Network 中确认只有一次 /events 请求，且返回 202。它只表示已接收，不是业务成功的独立证明。

**Python / Go：**请求成功时返回 202，响应结构为：

{
  "accepted": true,
  "receipt_id": "<receipt ID>",
  "duplicate": false,
  "status_url": "/api/v1/billing-events/<connection ID>/receipts/<receipt ID>"
}

202 表示已接收并入队，不代表归因、报表或计费已完成。保存回执 ID，用于检查后续处理结果。

• 401：API Key 缺失、无效或已撤销。
• 403 insufficient_scope：Key 缺少 Write 权限，请创建带 Write 权限的 Key。
• 404：连接不可用，或 Key 无权访问该品牌。
• 422 server_event_not_configured：安装 ID 尚未配置服务端事件。
• 422 event_handle_not_allowed：连接不允许该事件类型。
• 409：可能复用了事件 ID 或请求 ID，但修改了请求内容。
• 网络失败或 5xx：按现有任务系统的策略重试，保持事件内容和两个 ID 不变，不要无限连续重试。

仅对经批准的连接进行测试。Python/Go 辅助代码只有在调用发送函数时才会发送请求。

预配置连接

已有预绑定事件的连接，可以向 /api/v1/billing-events/{website_install_id}/preconfigured 发送最小请求体 {"arenza_visitor_id":"arz_v_…"}，同时携带相同的 Bearer、Content-Type 和 webhook-id 请求头。

这只适用于已绑定的事件，不支持任意事件类型。不要把这个最小请求体发送到前面的通用事件接口。

HTTP / curl 参考 · JSON Schema · 停止采集

已有 HMAC 签名接入仍可继续使用原连接 UUID 和签名请求头。API Key 接入方不需要获取或轮换这些签名密钥。

线上验证记录：2026-09-24列明了已验证的路径、部署版本、鉴权检查和验证范围。它不代表客户网站已完成安装或同意管理验收。