Integración desde el servidor

Hay datos que es más fiable enviar desde el servidor de su sitio web que desde el navegador: pedidos realizados y pagados, registros, cambios de estado y el catálogo de productos. El navegador puede cerrarse antes del envío o bloquear el rastreador; el servidor no. Encontrará ejemplos listos en Comunicaciones → Sitio web, en la pestaña Servidor.

Este artículo está dirigido a desarrolladores. El rastreador del sitio web se mantiene: cuenta las vistas y muestra los widgets, y el servidor lo complementa con los eventos importantes.

Pestaña «Servidor»

La pestaña tiene un selector de Lenguaje: PHP, Go, Node.js y Python. Los ejemplos están escritos sin bibliotecas de terceros e incluyen ya la dirección de OneTrace.pro, los nombres de los eventos y la propiedad con el id del producto según la configuración de su proyecto. El navegador recuerda el lenguaje elegido.

Para PHP, la pestaña también puede ofrecer una biblioteca lista para usar: un paquete de Composer con toda la API, reintentos ante fallos sin duplicados y un búfer de eventos. Si la pestaña muestra el bloque Biblioteca para PHP lista para usar, instale el paquete con el comando del ejemplo; los demás ejemplos muestran las mismas llamadas como solicitudes HTTP simples. En el mismo bloque hay un paquete para Laravel: los eventos se envían después de la respuesta o mediante la cola, una directiva añade el rastreador a las plantillas y los productos se sincronizan desde los modelos.

Pestaña «Servidor» con ejemplos en PHP

Claves

Clave de escritura (cdp_wk_…, tipo Escritura): para enviar eventos. Es la misma que la del código del rastreador.
Clave secreta (cdp_sk_…, tipo Secreta): para cargar el catálogo y gestionar el proyecto. Para el catálogo necesita el permiso «Carga y eliminación de productos» (products.write).

Las claves se crean en la sección Claves de API; pueden hacerlo «Propietario» y «Administrador». Guarde la clave secreta solo en el servidor y nunca la incluya en el código de las páginas.

Pasos

1. Variables de entorno

Guarde la dirección y las claves en variables de entorno del servidor, no en el código. Puede elegir los nombres de las variables:

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

2. Cliente

Función de envío: POST con JSON, clave en el encabezado Authorization: Bearer, tiempo de espera de 5 segundos y error ante cualquier respuesta distinta de 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. Inicio de sesión y registro

Envíe el id del usuario y sus atributos. La cookie cdp_aid es el identificador del visitante asignado por el rastreador. Envíelo como anonymousId y el perfil del cliente se unirá a sus visitas al sitio web.

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 },
});

No envíe atributos vacíos: el valor null elimina el atributo del perfil.

4. Pedido

Evento de compra con los productos del pedido. Un messageId basado en el número de pedido evita duplicados: una repetición con el mismo messageId en un plazo de 24 horas se descarta, por lo que el envío puede reintentarse con seguridad.

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 })),
  },
});

En PHP es la misma llamada cdp_send('track', [...]) con los mismos campos. El nombre del evento y la propiedad con el id del producto deben coincidir con la configuración de la sección Recomendaciones; de lo contrario, las compras no llegarán a los modelos.

5. Catálogo de productos

Los productos y las categorías se cargan con la clave secreta, hasta 1000 por solicitud. Volver a cargar el mismo id actualiza el producto.

cdp_send('products', [
    'items' => [[
        'id' => 'SKU-1', 'name' => 'Zapatillas', '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' => 'Calzado']],
], 'CDP_SECRET_KEY');

Si el catálogo ya existe como feed (YML, Google Merchant, CSV), es más sencillo conectar el feed en la sección Recomendaciones.

Pestaña «Servidor» con ejemplos en Node.js

Consejos

Envíe desde una cola en segundo plano y no en el manejador de la solicitud del cliente: así la respuesta del sitio web no depende de la red.
Reintente ante errores. La respuesta 202 indica que el evento fue aceptado y se procesará en segundos. Ante 429 (se superó el límite de solicitudes o la cuota mensual de eventos) y 5xx, repita la solicitud más tarde con el mismo messageId.
Límites: hasta 32 KB por mensaje, hasta 500 mensajes en /batch y un cuerpo de solicitud de hasta 1 MB. La clave de escritura acepta hasta 6000 solicitudes por minuto.
La restricción por dominios del sitio web no se aplica a las solicitudes desde el servidor.

La lista completa de métodos está en la referencia de la API: https://cdp.onetrace.pro/api/v1/openapi.json.