Intégration côté serveur

Certaines données sont envoyées de façon plus fiable depuis le serveur de votre site que depuis le navigateur : commandes passées et payées, inscriptions, changements de statut, catalogue de produits. Le navigateur peut être fermé avant l'envoi ou bloquer le traceur, le serveur non. Des exemples prêts à l'emploi sont réunis dans la section Engagement → Site web, onglet Serveur.

Cet article s'adresse aux développeurs. Le traceur du site reste en place : il compte les consultations et affiche les widgets, tandis que le serveur le complète avec les événements importants.

Onglet « Serveur »

L'onglet propose un sélecteur Langage : PHP, Go, Node.js et Python. Les exemples sont écrits sans bibliothèque tierce et contiennent déjà l'adresse de OneTrace.pro, les noms d'événements et la propriété de l'id du produit issus des paramètres de votre projet. Le langage choisi est mémorisé dans le navigateur.

Pour PHP, l'onglet peut aussi proposer une bibliothèque prête à l'emploi : un paquet Composer avec toute l'API, des nouvelles tentatives en cas d'échec sans doublons et un tampon d'événements. Si l'onglet affiche le bloc Bibliothèque PHP prête à l'emploi, installez le paquet avec la commande de l'exemple ; les autres exemples montrent les mêmes appels sous forme de simples requêtes HTTP. Le même bloc propose un paquet pour Laravel : les événements partent après la réponse ou via la file d'attente, une directive ajoute le traceur aux templates, les produits sont synchronisés depuis les modèles.

Onglet « Serveur » avec des exemples en PHP

Clés

Clé d'écriture (cdp_wk_…, type Écriture) : pour l'envoi d'événements. C'est la même que dans le code du traceur.
Clé secrète (cdp_sk_…, type Secrète) : pour le chargement du catalogue et la gestion du projet. Pour le catalogue, elle doit disposer de l'autorisation « Charger et supprimer des produits » (products.write).

Les clés se créent dans la section Clés API, par le « Propriétaire » ou l'« Administrateur ». Conservez la clé secrète uniquement sur le serveur et ne l'insérez jamais dans le code des pages.

Étapes

1. Variables d'environnement

Placez l'adresse et les clés dans les variables d'environnement du serveur plutôt que dans le code. Vous pouvez choisir vos propres noms de variables :

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

2. Client

Fonction d'envoi : POST avec un corps JSON, clé dans l'en-tête Authorization: Bearer, délai d'expiration de 5 secondes, erreur si la réponse n'est pas 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. Connexion et inscription

Transmettez l'id de l'utilisateur et ses attributs. Le cookie cdp_aid est l'identifiant du visiteur attribué par le traceur. Transmettez-le comme anonymousId : le profil du client sera alors fusionné avec ses visites sur le 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 },
});

Ne transmettez pas d'attributs vides : la valeur null supprime l'attribut du profil.

4. Commande

L'événement d'achat avec les produits de la commande. Un messageId construit à partir du numéro de commande protège des doublons : une répétition avec le même messageId dans les 24 heures est ignorée, l'envoi peut donc être retenté sans risque.

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, il s'agit du même appel cdp_send('track', [...]) avec les mêmes champs. Le nom de l'événement et la propriété de l'id du produit doivent correspondre aux paramètres de la section Recommandations, sinon les achats ne seront pas pris en compte par les modèles.

5. Catalogue de produits

Les produits et catégories se chargent avec la clé secrète, jusqu'à 1000 par requête. Un nouveau chargement du même id met le produit à jour.

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

Si le catalogue existe déjà sous forme de flux (YML, Google Merchant, CSV), il est plus simple de connecter ce flux dans la section Recommandations.

Onglet « Serveur » avec des exemples en Node.js

Conseils

Envoyez depuis une file d'attente en arrière-plan, et non dans le traitement de la requête du client : ainsi, la réponse du site ne dépend pas du réseau.
Réessayez en cas d'erreur. La réponse 202 signifie que l'événement est accepté et sera traité en quelques secondes. En cas de 429 (limite de requêtes ou quota mensuel d'événements dépassé) et de 5xx, renvoyez la requête plus tard avec le même messageId.
Limites : message jusqu'à 32 Ko, jusqu'à 500 messages dans /batch, corps de requête jusqu'à 1 Mo. La clé d'écriture accepte jusqu'à 6000 requêtes par minute.
La restriction par domaines du site ne s'applique pas aux requêtes serveur.

La liste complète des méthodes figure dans la référence de l'API : https://cdp.onetrace.pro/api/v1/openapi.json.