Integrazione lato server

Alcuni dati è più affidabile inviarli non dal browser ma dal server del Suo sito: ordini effettuati e pagati, registrazioni, cambi di stato, catalogo prodotti. Il browser può chiudersi prima dell'invio o bloccare il tracker, il server no. Gli esempi pronti si trovano nella sezione Coinvolgimento → Sito web, nella scheda Server.

Questo articolo è rivolto agli sviluppatori. Il tracker sul sito rimane comunque: conta le visualizzazioni e mostra i widget, mentre il server lo integra con gli eventi importanti.

Scheda «Server»

Nella scheda c'è il selettore Linguaggio: PHP, Go, Node.js e Python. Gli esempi sono scritti senza librerie esterne e contengono già l'indirizzo di OneTrace.pro, i nomi degli eventi e la proprietà con l'id del prodotto presi dalle impostazioni del Suo progetto. Il linguaggio scelto viene memorizzato nel browser.

Per PHP la scheda può proporre anche una libreria pronta all'uso: un pacchetto Composer con tutta l'API, ripetizioni in caso di errori senza duplicati e un buffer degli eventi. Se la scheda mostra il blocco Libreria PHP pronta all'uso, installi il pacchetto con il comando dell'esempio; gli altri esempi mostrano le stesse chiamate come semplici richieste HTTP. Nello stesso blocco trova un pacchetto per Laravel: gli eventi partono dopo la risposta o tramite la coda, una direttiva aggiunge il tracker ai template, i prodotti vengono sincronizzati dai modelli.

Scheda «Server» con esempi in PHP

Chiavi

Chiave di scrittura (cdp_wk_…, tipo Scrittura): per l'invio di eventi. È la stessa del codice del tracker.
Chiave segreta (cdp_sk_…, tipo Segreta): per il caricamento del catalogo e la gestione del progetto. Per il catalogo le serve il permesso «Caricamento ed eliminazione dei prodotti» (products.write).

Le chiavi si creano nella sezione Chiavi API; possono farlo il «Proprietario» e l'«Amministratore». Conservi la chiave segreta solo sul server e non la inserisca mai nel codice delle pagine.

Passaggi

1. Variabili d'ambiente

Inserisca l'indirizzo e le chiavi nelle variabili d'ambiente del server, non nel codice. I nomi delle variabili possono essere scelti liberamente:

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

2. Client

Funzione di invio: POST con JSON, chiave nell'intestazione Authorization: Bearer, timeout di 5 secondi, errore se la risposta non è 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. Accesso e registrazione

Trasmetta l'id dell'utente e gli attributi. Il cookie cdp_aid è l'identificatore del visitatore assegnato dal tracker. Lo trasmetta come anonymousId, così il profilo del cliente verrà unito alle sue visite al sito.

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

Non trasmetta attributi vuoti: il valore null elimina l'attributo dal profilo.

4. Ordine

Evento di acquisto con i prodotti dell'ordine. Un messageId basato sul numero d'ordine protegge dai duplicati: una ripetizione con lo stesso messageId entro 24 ore viene scartata, quindi l'invio può essere ripetuto in sicurezza.

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

In PHP si usa la stessa chiamata cdp_send('track', [...]) con gli stessi campi. Il nome dell'evento e la proprietà con l'id del prodotto devono coincidere con le impostazioni della sezione Raccomandazioni, altrimenti gli acquisti non entreranno nei modelli.

5. Catalogo prodotti

Prodotti e categorie si caricano con la chiave segreta, fino a 1000 per richiesta. Un nuovo caricamento con lo stesso id aggiorna il prodotto.

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

Se il catalogo è già disponibile come feed (YML, Google Merchant, CSV), è più semplice collegare il feed nella sezione Raccomandazioni.

Scheda «Server» con esempi in Node.js

Consigli

Invii da una coda in background, non nel gestore della richiesta del cliente: così la risposta del sito non dipende dalla rete.
Ripeta in caso di errore. La risposta 202 significa che l'evento è stato accettato e verrà elaborato in pochi secondi. In caso di 429 (superato il limite di richieste o la quota mensile di eventi) e di 5xx, ripeta la richiesta più tardi con lo stesso messageId.
Limiti: messaggio fino a 32 KB, fino a 500 messaggi in /batch, corpo della richiesta fino a 1 MB. La chiave di scrittura accetta fino a 6000 richieste al minuto.
La limitazione per domini del sito non si applica alle richieste dal server.

L'elenco completo dei metodi è nel riferimento dell'API: https://cdp.onetrace.pro/api/v1/openapi.json.