网站 SDK

1. 接入准备

网站安装 ID

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

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

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

上报条件

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

2. 接入示例

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.'));
// 继续原有业务流程。

3. 参数与响应

触发时机

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

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

访客关联

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

JavaScript（浏览器）

const visitorId = window.arenzaEvents.getVisitorId();

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

SDK 方法

停止采集

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

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

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

接口参考