HTTP Events API

Zaraz HTTP Events API 允许你从无法运行 Web API 的位置（例如服务器或移动应用）向 Zaraz 发送信息。它适用于跟踪发生在浏览器之外的事件，例如成功的交易、注册等。该 API 还支持批量发送多个事件。

配置 API 端点

除非你为其配置端点，否则该 API 处于禁用状态。端点决定 API 将在什么 URL 下可访问。例如，若将端点设为 /zaraz/api，且你的域名为 example.com，则对 API 的请求将前往 https://example.com/zaraz/api。

要启用 API 端点：

在 Cloudflare 仪表板中，前往 **Settings（设置）**页面。
Go to Settings ↗
在 Endpoints（端点）> HTTP Events API 下，设置你所需的路径。请记住该路径相对于你的域名，且必须以 / 开头。

发送事件

你为 API 配置的端点将接收带有 JSON 载荷的 POST 请求。以下是一个示例载荷：

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      }
    }
  ]
}

载荷必须包含 events 数组。该数组中的每个 Event Object 对应你希望 Zaraz 处理的一个事件。上面的示例类似于使用 Web API 调用 zaraz.track('transaction successful', { value: "200" })。

Event Object 包含 client 对象，你可以在其中传递有关事件本身的信息。你在 Event Object 中包含的每个键在 Zaraz 仪表板中都可作为 Track Property 使用。

有两个保留键：

__zarazTrack：此键的值将作为 Event Name 可用。这通常是你构建触发器的依据。在上面的示例中，将其设为 transaction successful 与使用 Web API 并调用 zaraz.track("transaction successful") 相同。
__zarazEcommerce：若希望 Zaraz 将该事件作为电子商务事件处理，需要将此键设为 true。

`system` 键

除 client 键外，你还可以使用 system 键包含有关事件来源设备的信息。例如，你可以提交 User-Agent 字符串、cookie 和屏幕分辨率。Zaraz 在连接不同第三方工具时会使用此信息。由于某些工具依赖特定字段，通常最好包含你能提供的所有信息。

在添加 system 信息后，与之前相同的载荷将类似于以下示例：

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      },
      "system": {
        "page": {
          "url": "https://example.com",
          "title": "My website"
        },
        "device": {
          "language": "en-US",
          "ip": "192.168.0.1"
        }
      }
    }
  ]
}

有关所有可用的 system 键，请参阅下表：

属性	类型	描述
`system.cookies`	Object	保存与事件关联设备上 cookie 的键值对象。
`system.device.ip`	String	与事件关联设备的 IP 地址。
`system.device.resolution`	String	与事件关联设备的屏幕分辨率，格式为 `WIDTHxHEIGHT`。
`system.device.viewport`	String	与事件关联设备的视口，格式为 `WIDTHxHEIGHT`。
`system.device.language`	String	与事件关联设备使用的语言代码。
`system.device.user-agent`	String	与事件关联设备的 `User-Agent` 字符串。
`system.page.title`	String	与事件关联页面的标题。
`system.page.url`	String	与事件关联页面的 URL。
`system.page.referrer`	String	事件发生时引荐页面的 URL。
`system.page.encoding`	String	与事件关联页面的编码。

处理 API 响应

对于载荷中的每个 Event Object，Zaraz 会以一个 Result Object 进行响应。Result Object 的顺序与你的 Event Object 顺序匹配。

取决于你使用 Zaraz 加载的工具，来自 API 的响应正文可能包含你希望处理的信息。这是因为某些工具没有完整的服务端实现，仍依赖 cookie、客户端 JavaScript 或类似机制。每个 Result Object 可包含以下信息：

Result 键	描述
`fetch`	工具希望从用户浏览器发送的 Fetch 请求。
`execute`	工具希望在用户浏览器中执行的 JavaScript 代码。
`return`	工具返回的信息。
`cookies`	工具希望为用户设置的 cookie。

你不必处理上述信息，但某些工具可能依赖这些信息才能正常工作。你可以在不处理上表信息的情况下开始使用 HTTP Events API，并在之后再进行相应调整。