OpenAI Ads Ölçüm Altyapısı: Pixel ve Conversions API Birlikte Nasıl Çalışır

OpenAI Ads dönüşüm ölçümü iki katmana dayanır: tarayıcıda çalışan bir JavaScript pixel ve sunucudan olay gönderen bir Conversions API¹²³. İkisi aynı dönüşüm taksonomisini paylaşır ama farklı yerlerde, farklı güçlü yanlarla çalışır. Bu yazı kurulum adımlarını anlatmaz; iki katmanın neyi yakaladığını, neden ikisinin birden gerektiğini ve aynı dönüşümü iki kez saymadan nasıl uzlaştıklarını anlatan kavramsal bir harita sunar.

Kurulumun teknik tarafı ayrı yazıların konusu: pixel kurulumu, Conversions API ile sunucu taraflı gönderim ve dedup mekaniği. Burada amaç, bu parçalara dalmadan önce zihinsel modeli oturtmak.

İki Katman, Tek Dönüşüm

Bir dönüşüm, örneğin bir sipariş, iki ayrı yoldan OpenAI’ye raporlanabilir:

• JavaScript pixel: Tarayıcıda çalışan oaiq SDK’sı. Sayfa yüklenince çekirdek kodu yükler, dönüşüm gerçekleştiğinde measure çağrısıyla olayı gönderir².
• Conversions API: Sunucudan sunucuya çalışan, olayları doğrudan OpenAI’ye gönderen uç nokta. Yalnızca sunucu tarafında çalışır³.

İkisi de aynı standart event isimlerini kullanır (page_viewed, contents_viewed, items_added, order_created, subscription_created gibi) ve aynı veri şekillerini paylaşır¹. Yani aynı dönüşüm dilini konuşurlar; fark, olayın nereden ve hangi koşulda gönderildiğindedir.

Her Katman Neyi Yakalar

İki katmanın güçlü yanları farklı. Pixel tarayıcıdaki canlı etkileşimi görür; Conversions API tarayıcının göremediği ya da güvenilir biçimde gönderemediği her şeyi taşır.

Boyut	JavaScript pixel	Conversions API
Çalıştığı yer	Tarayıcı (client-side)	Sunucu (server-side)
Tipik kullanım	Sayfa ve içerik görüntüleme, sepet, sipariş	Offline/CRM dönüşümleri, pixel’in ateşleyemediği durumlar
oppref kimliği	Açılış URL’inden otomatik yakalar, __oppref çerezinde saklar	Otomatik yakalamaz; kimlik elle taşınır
Reklam engelleyici etkisi	Engellenebilir	Etkilenmez
Güvenilirlik	Daha düşük	OpenAI tarafından daha güvenilir olarak tanımlanır

Pixel’in pratik bir avantajı, OpenAI’nin gizliliği koruyan kimliği olan oppref’i açılış sayfası URL’inden otomatik yakalayıp ilk taraf çerezde saklamasıdır; sonraki sayfa görüntülemelerinde bu kimlik taşınır². Conversions API tarafında ise bu kimlik otomatik gelmez; sunucudan gönderirken kimliği elle yakalayıp iletmek gerekir³.

Neden İki Katman Birden: Ölçüm Boşluğu

Tek başına tarayıcı tabanlı ölçüm, dönüşümlerin bir kısmını sistematik olarak kaybeder. Reklam engelleyiciler, consent reddi ve Safari/iOS gibi tarayıcıların çerez kısıtları üst üste bindiğinde, client-side ölçüm bir örnekleme dönüşür, sayıma değil. Bu, OpenAI Ads’e özgü bir sorun değil; client-side tracking’in neden tek başına yetersiz kaldığını ve consent kararlarının ölçümü nasıl etkilediğini daha önce ayrıntılı ele aldım.

Conversions API tam da bu boşluğu kapatmak için var. Sunucudan gönderilen olaylar reklam engelleyicilerin görüş alanı dışındadır, üçüncü taraf çereze ihtiyaç duymaz ve hangi verinin ne zaman gönderileceğine sunucu karar verir. OpenAI, Conversions API’yi pixel’den daha güvenilir bir kaynak olarak tanımlar ve mümkün olduğunda kullanılmasını önerir³. İki katman birlikte çalıştığında ölçüm, eksik bir örneklemden çok bir sayıma yaklaşır.

İki Katman Çakışmadan Nasıl Uzlaşır

İki katman aynı dönüşümü gönderdiğinde doğal bir risk doğar: çift sayım. OpenAI bunu bir tekilleştirme (dedup) mekanizmasıyla çözer. Aynı dönüşüm hem pixel hem Conversions API’den geliyorsa, iki tarafta da aynı değer kullanılır: pixel tarafında event_id, sunucu tarafında id ve her iki tarafta aynı Pixel ID²³. Custom event’lerde eşleşme olay adı yerine custom_event_name üzerinden yapılır.

Aynı siparişin iki katmandan da gönderildiği en yalın hali şöyle görünür. Tarayıcıda pixel ile:

oaiq(
  "measure",
  "order_created",
  { type: "contents", amount: 2599, currency: "USD" },
  { event_id: "order_12345" },
);

Sunucuda Conversions API ile, aynı kimlikle:

curl -X POST "https://bzr.openai.com/v1/events?pid=<PIXEL-ID>" \
  -H "Authorization: Bearer <API-KEY>" \
  -H "Content-Type: application/json" \
  --data '{
    "events": [{
      "id": "order_12345",
      "type": "order_created",
      "timestamp_ms": 1773892800000,
      "action_source": "web",
      "source_url": "https://magaza.example.com/odeme/onay",
      "data": { "type": "contents", "amount": 2599, "currency": "USD" }
    }]
  }'

Köprü noktası tek bir değer: pixel’deki event_id ile sunucudaki id aynı (order_12345) ve iki tarafta da aynı Pixel ID kullanılıyor. OpenAI bu eşleşmeden iki kaydın tek dönüşüm olduğunu anlıyor. Bu yüzden kimliğin iki tarafta da aynı, kararlı bir değerden (örneğin sipariş numarası) türetilmesi kritik. Tam kurulum ve sık yapılan hatalar ayrı yazıların konusu; buradaki örnek yalnızca eşleşmenin nasıl kurulduğunu gösteriyor.

Doğru kurulduğunda çift sayım olmaz; yanlış kurulduğunda ise raporlanan dönüşümler şişer ve ROAS bozulur. Tek kritik nokta, kimliğin gerçekten kararlı ve iki tarafta tutarlı olması.

Veri Akışı ve Standart Event Taksonomisi

İki katmanın paylaştığı ortak dil, standart event taksonomisidir. Her olayın bir type alanı ve tipe uygun bir veri şekli vardır: içerik ve sipariş olayları contents, lead ve kayıt olayları customer_action, abonelik ve deneme olayları plan_enrollment şeklini kullanır¹. Parasal değerler tam sayı ve ISO 4217 minor units biçiminde gönderilir; örneğin 129,99 dolar 12999 olarak iletilir¹.

Bu taksonomiyi doğru kullanmak, hangi olayın ne zaman gönderileceğini bilmek kadar, değeri doğru biçimde göndermeyi de gerektirir. Olayların tek tek hangi duruma karşılık geldiği ve değer gönderiminde sık yapılan hatalar, kavramsal haritanın değil uygulama yazılarının kapsamında.

Kimlik ve Gizlilik Katmanı

Her iki katman da dönüşümü bir kullanıcıyla eşleştirmek için isteğe bağlı kimlik alanları taşıyabilir. Bu alanlar ham değil, hash’lenmiş gönderilir: e-posta ve dış kimlik SHA-256 ile, küçük harfe çevrilip kırpıldıktan sonra iletilir; ham e-posta, ham dış kimlik ve telefon numarası asla gönderilmez³. Coğrafi bilgi, IP ve user-agent ham gönderilebilir.

Bu, gizlilik açısından bilinçli bir tasarım: eşleştirme kalitesini korurken kişisel veriyi açık biçimde paylaşmamayı amaçlar. Hash’leme, oppref kimliği, opt_out ve KVKK çerçevesi ayrı bir yazıda derinlemesine ele alınacak.

Nereden Başlamalı

Kavramsal model oturduktan sonra sıra uygulamaya gelir. Pratik bir başlangıç sırası şu: önce tarayıcı tarafını kurup temel dönüşümleri pixel ile yakalamak, ardından Conversions API’yi ekleyip kritik dönüşümleri sunucudan da göndererek ölçüm boşluğunu kapatmak, en sonunda da iki katmanı dedup ile uzlaştırmak. OpenAI’nin kendi tavsiyesi de tarayıcıda her zaman pixel’i kullanmak, sunucu API’sini ise sayfa kodundan değil sunucudan çağırmaktır².

İki katmanı ayrı ayrı kurmak teknik bir iş; ama hangi katmanın neyi çözdüğünü bilmeden kurmak, eksik ya da çift sayan bir ölçüme yol açar. Bu harita, sonraki adımların neden o sırayla geldiğini açıklıyor.

Footnotes

1. Supported events (OpenAI Developers) — standart event taksonomisi, veri şekilleri ve minor units kuralı (“12999 for $129.99 with currency: \"USD\"”). ↩ ↩² ↩³ ↩⁴
2. JavaScript Pixel (OpenAI Developers) — oaiq SDK kurulumu (bzrcdn.openai.com), measure çağrıları, oppref’in açılış URL’inden otomatik yakalanması ve __oppref çerezi, event_id ile browser/server dedup, “Always use the pixel on the browser. Do not call the server conversions API directly from page code.” ↩ ↩² ↩³ ↩⁴ ↩⁵
3. Conversions API (OpenAI Developers) — sunucu taraflı endpoint (bzr.openai.com/v1/events?pid=), dedup (API id = pixel event_id + aynı Pixel ID, custom event’lerde custom_event_name), kimlik eşleştirme (email_sha256/external_id_sha256, ham e-posta/dış kimlik/telefon asla; geo/IP/user-agent ham), “The Conversions API is a more reliable tracking source than the pixel alone.” ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

Önemli Noktalar

• 01 OpenAI Ads ölçümü iki katmandır: tarayıcı pixel'i (oaiq) ve sunucu taraflı Conversions API. İkisi aynı dönüşüm taksonomisini paylaşır.
• 02 Pixel client-side olayları ve oppref kimliğini otomatik yakalar; Conversions API offline/CRM olaylarını ve pixel'in ateşleyemediği durumları taşır, reklam engelleyiciden etkilenmez.
• 03 OpenAI Conversions API'yi pixel'den daha güvenilir tanımlar; ikisinin birlikte kullanımı sayıma yaklaşır, tek başına tarayıcı ölçümü örneklemde kalır.
• 04 Aynı dönüşümü iki taraf da gönderirse, ortak event_id/id + aynı Pixel ID ile dedup yapılır; custom event'lerde custom_event_name eşleşir.
• 05 Bu mimari Meta CAPI ve GA4 Measurement Protocol ile aynı prensibe dayanır; server-side tracking kurulumu olan ekip için tanıdık bir desendir.

Sık Sorulan Sorular (FAQ)

+ OpenAI Ads ölçümü neden iki katmandan oluşuyor?

Tek başına tarayıcı tabanlı ölçüm reklam engelleyiciler, consent reddi ve tarayıcı çerez kısıtları yüzünden dönüşümlerin bir kısmını kaybeder. JavaScript pixel client-side olayları yakalar; Conversions API ise sunucudan olay göndererek bu kayıpları telafi eder ve offline dönüşümleri taşır. OpenAI Conversions API'yi pixel'den daha güvenilir kaynak olarak tanımlar ve ikisinin birlikte kullanımını önerir.

+ Pixel ile Conversions API arasındaki fark nedir?

Pixel tarayıcıda çalışır, sayfadaki olayları (page_viewed, contents_viewed, order_created gibi) yakalar ve oppref kimliğini açılış sayfası URL'inden otomatik alır. Conversions API sunucudan sunucuya çalışır, offline ve CRM olaylarını ve pixel'in ateşleyemediği durumları gönderir; reklam engelleyici ve üçüncü taraf çerez kısıtlarından etkilenmez.

+ Aynı dönüşüm iki kez sayılır mı?

Hem pixel hem Conversions API aynı dönüşümü gönderirse, ortak bir event kimliği (pixel tarafında event_id, sunucu tarafında id) ve aynı Pixel ID kullanılarak tekilleştirilir. Custom event'lerde eşleşme custom_event_name üzerinden yapılır. Doğru kurulduğunda çift sayım olmaz; dedup mekaniğinin ayrıntıları ayrı bir yazının konusu.

+ Bu mimari Meta CAPI veya GA4'e benziyor mu?

Evet. OpenAI Ads Conversions API, Meta CAPI ve GA4 Measurement Protocol ile aynı mantığa dayanır: sunucu taraflı, daha güvenilir, tarayıcı kısıtlarından bağımsız bir ölçüm katmanı. Server-side tracking kurulumu olan bir ekip için OpenAI Ads ölçümü yeni bir paradigma değil, tanıdık bir desenin başka bir uygulamasıdır.