Sunucu entegrasyonu

Bazı verileri tarayıcıdan değil, web sitenizin sunucusundan göndermek daha güvenilirdir: verilen ve ödenen siparişler, kayıtlar, durum değişiklikleri, ürün kataloğu. Tarayıcı gönderimden önce kapanabilir veya izleyiciyi engelleyebilir, sunucu ise bunu yapmaz. Hazır örnekler İletişim → Web sitesi bölümündeki Sunucu sekmesinde toplanmıştır.

Bu makale geliştiriciler içindir. Web sitesindeki izleyici yerinde kalır: görüntülemeleri sayar ve widget'ları gösterir, sunucu ise onu önemli olaylarla tamamlar.

“Sunucu” sekmesi

Sekmede bir Dil seçici bulunur: PHP, Go, Node.js ve Python. Örnekler üçüncü taraf kitaplıklar olmadan yazılmıştır; OneTrace.pro adresi, olay adları ve projenizin ayarlarındaki ürün id özelliği zaten eklenmiştir. Seçilen dil tarayıcıda hatırlanır.

PHP için sekme hazır bir kütüphane de sunabilir: tüm API'yi, hatalarda çift kayıt oluşturmadan yeniden denemeyi ve olay arabelleğini içeren bir Composer paketi. Sekmede Hazır PHP kütüphanesi bloğu varsa paketi örnekteki komutla kurun; diğer örnekler aynı çağrıları düz HTTP istekleri olarak gösterir. Aynı blokta bir Laravel paketi de vardır: olaylar yanıttan sonra veya kuyruk üzerinden gönderilir, bir direktif izleyiciyi şablonlara ekler, ürünler modellerden eşitlenir.

PHP örnekleriyle “Sunucu” sekmesi

Anahtarlar

Yazma anahtarı (cdp_wk_…, Write türü): olay göndermek için. İzleyici kodundakiyle aynıdır.
Gizli anahtar (cdp_sk_…, Secret türü): katalog yüklemek ve projeyi yönetmek için. Katalog için “Ürün yükleme ve silme” (products.write) yetkisine ihtiyaç duyar.

Anahtarlar API anahtarları bölümünde oluşturulur; bunu “Sahip” ve “Yönetici” yapabilir. Gizli anahtarı yalnızca sunucuda saklayın ve asla sayfa koduna eklemeyin.

Adımlar

1. Ortam değişkenleri

Adresi ve anahtarları koda değil, sunucunun ortam değişkenlerine koyun. Değişken adlarını kendiniz seçebilirsiniz:

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

2. İstemci

Gönderim fonksiyonu: JSON ile POST, Authorization: Bearer başlığında anahtar, 5 saniyelik zaman aşımı, yanıt 2xx değilse hata.

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. Giriş ve kayıt

Kullanıcı id'sini ve nitelikleri gönderin. cdp_aid çerezi, izleyicinin verdiği ziyaretçi tanımlayıcısıdır. Bunu anonymousId olarak gönderin; müşterinin profili web sitesine yaptığı ziyaretlerle birleştirilir.

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

Boş nitelik göndermeyin: null değeri niteliği profilden siler.

4. Sipariş

Siparişin ürünlerini içeren satın alma olayı. Sipariş numarasından oluşturulan messageId kopyalara karşı korur: aynı messageId ile 24 saat içinde gelen tekrar atılır, bu nedenle gönderimi güvenle yineleyebilirsiniz.

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

PHP'de aynı alanlarla aynı cdp_send('track', [...]) çağrısı kullanılır. Olay adı ve ürün id özelliği Öneriler bölümündeki ayarlarla eşleşmelidir, aksi halde satın almalar modellere dahil edilmez.

5. Ürün kataloğu

Ürünler ve kategoriler gizli anahtarla, istek başına en fazla 1000 adet olarak yüklenir. Aynı id ile yeniden yükleme ürünü günceller.

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

Katalog zaten bir feed olarak mevcutsa (YML, Google Merchant, CSV) feed'i Öneriler bölümünde bağlamak daha kolaydır.

Node.js örnekleriyle “Sunucu” sekmesi

İpuçları

Arka plan kuyruğundan gönderin, müşterinin isteğini işleyen kodun içinden değil: böylece web sitesinin yanıtı ağa bağlı olmaz.
Hatalarda yeniden deneyin. 202 yanıtı, olayın kabul edildiği ve saniyeler içinde işleneceği anlamına gelir. 429 (istek sınırı veya aylık olay kotası aşıldı) ve 5xx durumlarında isteği daha sonra aynı messageId ile yineleyin.
Sınırlar: mesaj başına en fazla 32 KB, /batch içinde en fazla 500 mesaj, istek gövdesi en fazla 1 MB. Yazma anahtarı dakikada en fazla 6000 istek kabul eder.
Web sitesi alan adı kısıtlaması sunucu istekleri için geçerli değildir.

Yöntemlerin tam listesi API başvurusundadır: https://cdp.onetrace.pro/api/v1/openapi.json.