Integração pelo servidor

Alguns dados são enviados com mais segurança pelo servidor do seu site do que pelo navegador: pedidos feitos e pagos, cadastros, mudanças de status, o catálogo de produtos. O navegador pode fechar antes do envio ou bloquear o rastreador; o servidor, não. Os exemplos prontos estão em Engajamento → Site, na aba Servidor.

Este artigo é para desenvolvedores. O rastreador no site continua necessário: ele conta as visualizações e exibe os widgets, e o servidor o complementa com os eventos importantes.

Aba “Servidor”

A aba tem o seletor Linguagem: PHP, Go, Node.js e Python. Os exemplos são escritos sem bibliotecas de terceiros e já trazem o endereço do OneTrace.pro, os nomes dos eventos e a propriedade com o id do produto das configurações do seu projeto. A linguagem escolhida fica salva no navegador.

Para PHP, a aba também pode oferecer uma biblioteca pronta: um pacote do Composer com toda a API, novas tentativas em caso de falha sem duplicatas e um buffer de eventos. Se a aba mostrar o bloco Biblioteca PHP pronta, instale o pacote com o comando do exemplo; os demais exemplos mostram as mesmas chamadas como requisições HTTP simples. No mesmo bloco há um pacote para Laravel: os eventos são enviados após a resposta ou pela fila, uma diretiva adiciona o rastreador aos templates e os produtos são sincronizados a partir dos modelos.

Aba “Servidor” com exemplos em PHP

Chaves

Chave de gravação (cdp_wk_…, tipo Write): para enviar eventos. É a mesma do código do rastreador.
Chave secreta (cdp_sk_…, tipo Secret): para enviar o catálogo e gerenciar o projeto. Para o catálogo, ela precisa da permissão “Enviar e excluir produtos” (products.write).

As chaves são criadas na seção Chaves de API, o que é permitido para “Proprietário” e “Administrador”. Guarde a chave secreta apenas no servidor e nunca a coloque no código das páginas.

Etapas

1. Variáveis de ambiente

Coloque o endereço e as chaves nas variáveis de ambiente do servidor, e não no código. Os nomes das variáveis podem ser os que você preferir:

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

2. Cliente

Função de envio: POST com JSON, chave no cabeçalho Authorization: Bearer, tempo limite de 5 segundos e erro em qualquer resposta diferente 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}`);
}

Envie o id do usuário e os atributos. O cookie cdp_aid é o identificador de visitante gerado pelo rastreador. Envie-o como anonymousId, e o perfil do cliente é unido às visitas dele ao site.

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

Não envie atributos vazios: o valor null remove o atributo do perfil.

4. Pedido

Evento de compra com os produtos do pedido. Um messageId gerado a partir do número do pedido evita duplicatas: uma repetição com o mesmo messageId em até 24 horas é descartada, então o envio pode ser repetido com segurança.

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

Em PHP, a chamada é a mesma, cdp_send('track', [...]), com os mesmos campos. O nome do evento e a propriedade com o id do produto devem coincidir com as configurações da seção Recomendações; caso contrário, as compras não entram nos modelos.

5. Catálogo de produtos

Produtos e categorias são enviados com a chave secreta, até 1000 por requisição. Enviar novamente o mesmo id atualiza o produto.

cdp_send('products', [
    'items' => [[
        'id' => 'SKU-1', 'name' => 'Tênis', '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' => 'Calçados']],
], 'CDP_SECRET_KEY');

Se o catálogo já existir como feed (YML, Google Merchant, CSV), é mais simples conectar o feed na seção Recomendações.

Aba “Servidor” com exemplos em Node.js

Dicas

Envie a partir de uma fila em segundo plano, e não no manipulador da requisição do cliente: assim a resposta do site não depende da rede.
Repita em caso de erro. A resposta 202 indica que o evento foi aceito e será processado em segundos. Em caso de 429 (limite de requisições ou cota mensal de eventos excedidos) e 5xx, repita a requisição mais tarde com o mesmo messageId.
Limites: até 32 KB por mensagem, até 500 mensagens em /batch e corpo da requisição de até 1 MB. A chave de gravação aceita até 6000 requisições por minuto.
A restrição por domínios do site não se aplica às requisições do servidor.

A lista completa de métodos está na referência da API: https://cdp.onetrace.pro/api/v1/openapi.json.