Arenza 事件接入

English | 简体中文

当访客完成你关注的操作，例如预约确认、询价提交或试用开通，可以通过这份文档将事件上报给 Arenza。由你的业务代码决定何时上报；访客 ID 用于关联该访客的网站访问记录。

在网页中上报，选择 HTML 或 JavaScript；在后端上报，选择 Python 或 Go。先准备接入凭据，再复制对应示例。同一次事件只选一种上报方式，不要同时从网页和后端发送。浏览器目前只记录通用交互；服务端可使用已配置的事件类型。

接入准备 · 接入示例 · 参数与响应

1. 接入准备

网站安装 ID

打开 Arenza Portal → AI Integrations，选择你的品牌，复制 Website install ID。它以 arz_pub_ 开头。用这个值替换示例中的 YOUR_INSTALL_ID。

这是公开的品牌安装标识，不是秘密 API Key。HTML/JavaScript 通过它获取短期会话凭证，SDK 会在 track() 时自动携带凭证。凭证绑定访客和网页来源，不证明网站归属，也不证明业务已成功完成。

浏览器来源限制是可选配置。没有配置 reporting_origins 时，其他合法 HTTPS 来源也能用这个公开 ID 获取会话；配置后，上报来源必须符合限制。详见浏览器鉴权说明（英文）。

服务端凭据

Python / Go 使用现有的 Personal Access Token 作为 API Key：

1. 打开 AI Integrations → Personal Access Tokens。
2. 点击 New token，填写名称，例如 Server events，勾选 Write。
3. 点击 Create token，复制以 arn_pat_ 开头的 Key。完整 Key 只显示一次。
4. 在后端将 Key 配置为 ARENZA_API_KEY，将 Website install ID 配置为 ARENZA_INSTALL_ID。

这些是示例使用的环境变量名。通过服务端密钥管理服务注入 Key，不要放进网页代码。不需要另外申请 Signing Secret。接收端会校验 Authorization: Bearer <API_KEY>、Write 权限和对目标品牌的访问权限。

更换 Key 时，先创建新 Key 并更新后端，再在同一个令牌列表撤销旧 Key。撤销后，使用旧 Key 的后续请求会被拒绝。

创建 Key 不等于配置事件。 品牌必须已有服务端事件连接及允许的 event_handle。仅用于网站采集的安装 ID 会返回 422 server_event_not_configured；创建 Key 不会自动创建计费合同，也不会启用任意事件类型。尚未配置时，请先与 Arenza 确认该品牌支持的事件。

上报条件

• 使用 HTTPS 网站；如配置了来源限制，确认网站来源符合限制。
• 由你的业务逻辑决定触发条件。除非确实要记录两个事件，否则不要同时上报按钮点击和业务成功结果。

2. 接入示例

每次事件只选择一种方式：

HTML | JavaScript | Python | Go

HTML/JavaScript 在网页中执行；Python/Go 在后端执行。后端事件如需关联网站访客，按访客关联传递访客 ID。

HTML

初始化

替换 YOUR_INSTALL_ID。通过网站现有的同意管理机制，在访客同意分析追踪后，将这段代码加入网页。第一个标签加载并初始化 SDK；第二个让后续事件代码等待初始化完成。

HTML

<script src="https://arenza.ai/sdk/v1.js"
        data-arenza-install-id="YOUR_INSTALL_ID"></script>
<script>
  window.arenzaReady = window.arenzaEvents.init()
    .then(() => window.arenzaEvents);
  window.arenzaReady.catch(() => {
    console.warn('Arenza initialization failed.');
  });
</script>

上报事件

以预约确认为例：找到预约接口返回成功后的处理代码，把这段代码放在那里，不要放进失败分支。

JavaScript（浏览器）

// 你的业务代码已确认预约成功，或确认了你选择的其他触发条件。
void window.arenzaReady
  .then((client) => client.track())
  .catch(() => console.warn('Arenza event could not be sent.'));
// 继续原有业务流程。

JavaScript

初始化

用 script 标签加载 https://arenza.ai/sdk/v1.js，不要添加 data-arenza-install-id。在脚本加载完成、且访客同意分析追踪后，执行一次这段初始化代码。

JavaScript（浏览器）

// ArenzaBilling 由已加载的 SDK 提供。
window.arenzaEvents = window.ArenzaBilling.create({
  endpoint: 'https://api.arenza.ai/api/v1/events/collect/YOUR_INSTALL_ID',
  consent: true,
});
window.arenzaReady = (async () => {
  await window.arenzaEvents.init();
  return window.arenzaEvents;
})();
window.arenzaReady.catch(() => console.warn('Arenza initialization failed.'));

初始化会记录一次页面访问并准备会话凭证，不会发送你的业务事件。访客 ID、请求 ID 和浏览器鉴权由 SDK 处理。

上报事件

以预约确认为例：找到预约接口返回成功后的处理代码，把这段代码放在那里，不要放进失败分支。

JavaScript（浏览器）

// 你的业务代码已确认预约成功，或确认了你选择的其他触发条件。
void window.arenzaReady
  .then((client) => client.track())
  .catch(() => console.warn('Arenza event could not be sent.'));
// 继续原有业务流程。

Python

配置接入准备中的 ARENZA_API_KEY 和 ARENZA_INSTALL_ID，准备服务端字段中的事件对象，以及已保存的本次请求 UUID。不需要浏览器会话凭证。

将 HTTP 辅助代码复制到项目中，文件名为 arenza_events.py，然后在事件处理代码中调用：

from arenza_events import send_event

# event：已保存的事件对象，结构见“服务端字段”。
# delivery_id：本次请求的 UUID，只生成一次，重试时复用。
receipt = send_event(event, delivery_id)
# 将 receipt["receipt_id"] 保存到本次上报记录中。

Go

配置接入准备中的 ARENZA_API_KEY 和 ARENZA_INSTALL_ID，准备服务端字段中的事件对象，以及已保存的本次请求 UUID。不需要浏览器会话凭证。

将 HTTP 辅助代码复制到 Go 模块的 arenza 包中（Go 1.18+），在事件处理代码中导入该包后调用：

// event：已保存的事件 map，结构见“服务端字段”。
// deliveryID：本次请求的 UUID。ctx：当前任务的 context。
receipt, err := arenza.SendEvent(ctx, event, deliveryID)
if err != nil {
    return err // 交给现有任务系统处理错误或重试。
}
// 将 receipt.ReceiptID 保存到本次上报记录中。

3. 参数与响应

触发时机

由你决定执行示例代码的时机：

**当前限制：**浏览器 track() 不支持命名事件类型。这些只是触发位置示例，不代表 Arenza 报表会区分对应的业务事件名称。track('booking_confirmed') 不受支持。同一次事件只选 SDK、直接 HTTP 或服务端上报中的一种方式。

访客关联

按 HTML 或 JavaScript 示例安装后，读取访客 ID：

JavaScript（浏览器）

const visitorId = window.arenzaEvents.getVisitorId();

将该值作为 arenza_visitor_id 加入发往你自己后端的现有业务请求。后端应将它与业务记录一起保存，供异步任务上报时使用。这个读取方法不发送事件；已经由后端上报的同一次事件，不要再调用浏览器 track()。

服务端字段

请求地址：

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 辅助代码只有在调用发送函数时才会发送请求。

SDK 方法

预配置连接

已有预绑定事件的连接，可以向 /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（英文）列明了已验证的路径、部署版本、鉴权检查和验证范围。它不代表客户网站已完成安装或同意管理验收。