Интеграция с сервера

Часть данных надёжнее отправлять не из браузера, а с сервера вашего сайта: оформленные и оплаченные заказы, регистрации, смену статусов, товарный каталог. Браузер может закрыться до отправки или заблокировать трекер, сервер — нет. Готовые примеры собраны в разделе Коммуникации → Сайт на вкладке Сервер.

Эта статья для разработчиков. Трекер на сайте при этом остаётся: он считает просмотры и показывает виджеты, а сервер дополняет его важными событиями.

Вкладка «Сервер»

На вкладке есть переключатель Язык: 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. Клиент

Функция отправки: POST с JSON, ключ в заголовке 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 из номера заказа защищает от дублей: повтор с тем же messageId в течение 24 часов отбрасывается, поэтому отправку можно безопасно повторить.

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 КБ, до 500 сообщений в /batch, тело запроса до 1 МБ. Ключ записи принимает до 6000 запросов в минуту.
Ограничение по доменам сайта на серверные запросы не действует.

Полный перечень методов — в справочнике API: https://cdp.onetrace.pro/api/v1/openapi.json.