服务器端集成

有些数据从网站服务器发送比从浏览器发送更可靠：已下单和已支付的订单、注册、状态变更、商品目录。浏览器可能在发送前被关闭，或屏蔽追踪器，而服务器不会。现成的示例位于用户互动 → 网站的服务器选项卡中。

本文面向开发人员。网站上的追踪器仍然保留：它负责统计浏览和展示小组件，服务器则用重要事件对其进行补充。

“服务器”选项卡

该选项卡中有一个语言切换器：PHP、Go、Node.js 和 Python。示例不依赖第三方库，并已填入 OneTrace.pro 的地址、事件名称以及项目设置中的商品 id 属性。所选语言会保存在浏览器中。

对于 PHP，该选项卡还可能提供现成的库：一个 Composer 包，包含完整的 API、失败时不产生重复的自动重试以及事件缓冲。如果选项卡中显示 现成的 PHP 库 区块，请使用示例中的命令安装该包；其他示例以普通 HTTP 请求的形式展示相同的调用。同一区块中还有 Laravel 扩展包：事件在响应之后或通过队列发送，指令会将跟踪器加入模板，商品从模型同步。

显示 PHP 示例的“服务器”选项卡

密钥

写入密钥（cdp_wk_…，Write 类型）：用于发送事件。与追踪代码中使用的密钥相同。
私密密钥（cdp_sk_…，Secret 类型）：用于上传目录和管理项目。上传目录需要“上传和删除商品”权限（products.write）。

密钥在API 密钥板块中创建，“所有者”和“管理员”可以执行此操作。私密密钥只能保存在服务器上，切勿放入页面代码。

步骤

1. 环境变量

请将地址和密钥放在服务器的环境变量中，而不是代码中。变量名可以自行选择：

CDP_URL=https://cdp.onetrace.pro/api/v1
CDP_WRITE_KEY=cdp_wk_…
CDP_SECRET_KEY=cdp_sk_…

2. 客户端

发送函数：以 JSON 格式发送 POST 请求，密钥放在 Authorization: Bearer 请求头中，超时 5 秒，响应不是 2xx 时报错。

PHP：

function cdp_send(string $path, array $body, string $keyEnv = 'CDP_WRITE_KEY'): void
{
    $ch = curl_init(getenv('CDP_URL') . '/' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'Authorization: Bearer ' . getenv($keyEnv)],
        CURLOPT_POSTFIELDS => json_encode(array_filter($body, fn ($v) => $v !== null), JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 5,
    ]);
    curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    if ($status >= 300) {
        throw new RuntimeException("CDP: HTTP {$status}");
    }
}

Node.js：

export async function cdpSend(path, body, key = process.env.CDP_WRITE_KEY) {
  const response = await fetch(`${process.env.CDP_URL}/${path}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(5000),
  });
  if (!response.ok) throw new Error(`CDP: HTTP ${response.status}`);
}

3. 登录和注册

传递用户 id 和属性。Cookie cdp_aid 是追踪器分配的访客标识符。将其作为 anonymousId 传递，客户的档案就会与其网站访问记录合并。

cdp_send('identify', [
    'userId' => (string) $user->id,
    'anonymousId' => $_COOKIE['cdp_aid'] ?? null,
    'traits' => ['email' => $user->email, 'first_name' => $user->first_name],
]);

await cdpSend('identify', {
  userId: String(user.id),
  anonymousId: req.cookies?.cdp_aid,
  traits: { email: user.email, first_name: user.firstName },
});

不要传递空属性：值为 null 会从档案中删除该属性。

4. 订单

带有订单商品的购买事件。使用订单号生成的 messageId 可以防止重复：24 小时内具有相同 messageId 的重复事件会被丢弃，因此可以安全地重试发送。

await cdpSend('track', {
  messageId: `order-${order.id}`,
  userId: String(order.userId),
  anonymousId: req.cookies?.cdp_aid,
  event: 'order_completed',
  properties: {
    order_id: String(order.id),
    amount: order.total,
    products: order.lines.map((line) => ({ product_id: String(line.productId), quantity: line.quantity, price: line.price })),
  },
});

在 PHP 中，使用相同字段调用 cdp_send('track', [...]) 即可。事件名称和商品 id 属性必须与推荐板块中的设置一致，否则购买数据不会进入模型。

5. 商品目录

商品和类目使用私密密钥上传，每次请求最多 1000 个。再次上传相同的 id 会更新商品。

cdp_send('products', [
    'items' => [[
        'id' => 'SKU-1', 'name' => '运动鞋', 'url' => 'https://shop.example.com/p/sku-1',
        'image' => 'https://shop.example.com/i/sku-1.jpg', 'price' => 4990, 'currency' => 'RUB',
        'available' => true, 'category_ids' => ['shoes'], 'brand' => 'Brand',
    ]],
    'categories' => [['id' => 'shoes', 'name' => '鞋类']],
], 'CDP_SECRET_KEY');

如果目录已有商品源形式（YML、Google Merchant、CSV），在推荐板块中接入商品源会更简单。

显示 Node.js 示例的“服务器”选项卡

建议

从后台队列发送，而不是在处理客户请求的过程中发送：这样网站的响应不会受网络影响。
**出错时重试。**响应 202 表示事件已被接收，并将在几秒钟内处理。遇到 429（超出请求限额或每月事件配额）和 5xx 时，请稍后使用相同的 messageId 重试请求。
**限制：**单条消息不超过 32 KB，/batch 中最多 500 条消息，请求体不超过 1 MB。写入密钥每分钟最多接受 6000 次请求。
网站域名限制不适用于服务器端请求。

完整的方法列表请参阅 API 参考：https://cdp.onetrace.pro/api/v1/openapi.json。