Serverseitige Integration

Manche Daten senden Sie zuverlässiger nicht aus dem Browser, sondern vom Server Ihrer Website: abgeschlossene und bezahlte Bestellungen, Registrierungen, Statusänderungen, den Produktkatalog. Der Browser kann vor dem Senden geschlossen werden oder den Tracker blockieren, der Server nicht. Fertige Beispiele finden Sie im Bereich Kommunikation → Website auf dem Tab Server.

Dieser Artikel richtet sich an Entwickler. Der Tracker auf der Website bleibt dabei bestehen: Er erfasst Seitenaufrufe und zeigt Widgets an, der Server ergänzt ihn um wichtige Ereignisse.

Tab „Server“

Auf dem Tab gibt es den Umschalter Sprache: PHP, Go, Node.js und Python. Die Beispiele kommen ohne Fremdbibliotheken aus, die Adresse von OneTrace.pro, die Ereignisnamen und die Eigenschaft mit der Produkt-ID aus Ihren Projekteinstellungen sind bereits eingesetzt. Die gewählte Sprache merkt sich der Browser.

Für PHP kann der Tab auch eine fertige Bibliothek anbieten – ein Composer-Paket mit der gesamten API, Wiederholungen bei Fehlern ohne Duplikate und einem Ereignispuffer. Wenn der Tab den Block Fertige PHP-Bibliothek zeigt, installieren Sie das Paket mit dem Befehl aus dem Beispiel; die übrigen Beispiele zeigen dieselben Aufrufe als einfache HTTP-Anfragen. Im selben Block finden Sie ein Paket für Laravel: Ereignisse werden nach der Antwort oder über die Queue gesendet, eine Direktive fügt den Tracker in die Templates ein, Produkte werden aus den Modellen synchronisiert.

Tab „Server“ mit PHP-Beispielen

Schlüssel

Schreibschlüssel (cdp_wk_…, Typ Write) – zum Senden von Ereignissen. Derselbe wie im Tracker-Code.
Geheimer Schlüssel (cdp_sk_…, Typ Secret) – zum Hochladen des Katalogs und zur Verwaltung des Projekts. Für den Katalog benötigt er die Berechtigung „Produkte hochladen und löschen“ (products.write).

Schlüssel erstellen Sie im Bereich API-Schlüssel – das können „Inhaber“ und „Administrator“. Bewahren Sie den geheimen Schlüssel nur auf dem Server auf und fügen Sie ihn niemals in Seitencode ein.

Schritte

1. Umgebungsvariablen

Legen Sie Adresse und Schlüssel in Umgebungsvariablen des Servers ab, nicht im Code. Die Variablennamen können Sie frei wählen:

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

2. Client

Sendefunktion: POST mit JSON, Schlüssel im Header Authorization: Bearer, Timeout 5 Sekunden, Fehler bei einer Antwort außerhalb von 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. Anmeldung und Registrierung

Übergeben Sie die Benutzer-ID und Merkmale. Das Cookie cdp_aid ist die Besucherkennung, die der Tracker vergeben hat. Übergeben Sie sie als anonymousId, dann wird das Kundenprofil mit seinen Website-Besuchen zusammengeführt.

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

Übergeben Sie keine leeren Merkmale: Der Wert null löscht das Merkmal aus dem Profil.

4. Bestellung

Kaufereignis mit den Produkten der Bestellung. Eine messageId aus der Bestellnummer schützt vor Duplikaten: Eine Wiederholung mit derselben messageId innerhalb von 24 Stunden wird verworfen, daher können Sie das Senden gefahrlos wiederholen.

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 ist es derselbe Aufruf cdp_send('track', [...]) mit denselben Feldern. Ereignisname und Eigenschaft mit der Produkt-ID müssen mit den Einstellungen im Bereich Empfehlungen übereinstimmen, sonst fließen Käufe nicht in die Modelle ein.

5. Produktkatalog

Produkte und Kategorien werden mit dem geheimen Schlüssel hochgeladen, bis zu 1000 pro Anfrage. Ein erneuter Upload mit derselben id aktualisiert das Produkt.

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' => 'Schuhe']],
], 'CDP_SECRET_KEY');

Liegt der Katalog bereits als Feed vor (YML, Google Merchant, CSV), ist es einfacher, den Feed im Bereich Empfehlungen anzubinden.

Tab „Server“ mit Node.js-Beispielen

Tipps

Senden Sie aus einer Hintergrund-Warteschlange, nicht im Request-Handler des Kunden: So hängt die Antwortzeit der Website nicht vom Netzwerk ab.
Wiederholen Sie bei Fehlern. Die Antwort 202 bedeutet, dass das Ereignis angenommen wurde und in Sekunden verarbeitet wird. Bei 429 (Anfragelimit oder monatliches Ereigniskontingent überschritten) und 5xx wiederholen Sie die Anfrage später mit derselben messageId.
Grenzen: Nachricht bis 32 KB, bis zu 500 Nachrichten in /batch, Anfragekörper bis 1 MB. Der Schreibschlüssel nimmt bis zu 6000 Anfragen pro Minute an.
Die Beschränkung auf Website-Domains gilt nicht für serverseitige Anfragen.

Die vollständige Liste der Methoden finden Sie in der API-Referenz: https://cdp.onetrace.pro/api/v1/openapi.json.