OpenAI Ads pixel kurulumu üç adımdan oluşuyor:
- Snippet’i sayfaya ekle
oaiq("init")ile Pixel ID’yi tanımla- Dönüşüm gerçekleştiğinde
oaiq("measure")çağır1
Bu rehber her adımı kod örnekleriyle gösterir. Pixel’in ölçüm mimarisindeki yeri ve sunucu tarafıyla nasıl uzlaştığı ayrı bir yazının konusu; burada odak, tarayıcı tarafını çalışır hale getirmek.
Adım Bir: Snippet’i Sayfaya Ekle
Snippet, dönüşüm yakalanan her sayfanın <head> bölümüne, mümkün olduğunca üste eklenir. Amaç, erken gerçekleşen dönüşümlerin pixel yüklenmeden kaçmasını önlemek1. Pixel ID’yi Ads Manager’ın conversions sekmesinden edinmek gerekiyor. Elbette Ads Manager sadece erişim sunulan ülkelerde mevcut. OpenAI’nin duyurularını takip etmek önemli.
<script>
(function (w, d, s, u) {
if (w.oaiq) return;
var q = function () {
q.q.push(arguments);
};
q.q = [];
w.oaiq = q;
var js = d.createElement(s);
js.async = true;
js.src = u;
var f = d.getElementsByTagName(s)[0];
f.parentNode.insertBefore(js, f);
})(window, document, "script", "https://bzrcdn.openai.com/sdk/oaiq.min.js");
oaiq("init", { pixelId: "<PIXEL-ID>" });
</script>Test sırasında init nesnesine debug: true eklemek, SDK etkinliğini konsola yazdırır ve kurulumu doğrulamayı kolaylaştırır1.
Adım İki: init ile Kullanıcı Verisini Ekle
Kullanıcı eşleştirme alanları istek kapsamlıdır: tekil measure çağrılarına değil, init çağrısına eklenir. Tüm alanlar opsiyoneldir, yalnızca elde olan gönderilir. E-posta ve dış kimlik ham değil, SHA-256 ile hash’lenmiş iletilir; ham e-posta, ham dış kimlik ve telefon numarası asla gönderilmez1.
oaiq("init", {
pixelId: "<PIXEL-ID>",
user: {
email_sha256: "b4c9a289...",
external_id_sha256: "73d83a07...",
country: "US",
city: "San Francisco",
zip_code: "94107",
},
});Kullanıcı verisi sonradan geliyorsa, örneğin giriş yapıldıktan sonra, init tam user nesnesiyle tekrar çağrılır; ilk init’ten sonra pixelId atlanabilir1. Hash’leme yöntemi, oppref kimliği ve KVKK çerçevesi gizlilik tarafının konusu ve ayrı bir yazıda ele alınacak.
Adım Üç: measure ile Dönüşümleri Gönder
Dönüşüm gerçekleştiğinde measure çağrılır. Argüman sırası: komut ("measure"), event adı, event verisi ve opsiyonel options nesnesi1. Veri nesnesinin type alanı event’in şekline uyar: içerik ve sipariş olayları contents, lead ve kayıt olayları customer_action, abonelik ve deneme olayları plan_enrollment2.
| Event | Veri tipi (type) | Ne zaman |
|---|---|---|
page_viewed | contents | Önemli bir sayfa görüntülenir |
contents_viewed | contents | Ürün, içerik ya da öğe görüntülenir |
items_added | contents | Sepete ya da seçime öğe eklenir |
order_created | contents | Satın alma tamamlanır |
lead_created | customer_action | Lead formu gönderilir |
registration_completed | customer_action | Kayıt tamamlanır |
appointment_scheduled | customer_action | Toplantı ya da demo ayarlanır |
subscription_created | plan_enrollment | Ücretli abonelik başlar |
trial_started | plan_enrollment | Ücretsiz deneme başlar |
// Sayfa ve içerik görüntüleme
oaiq("measure", "page_viewed", {
type: "contents",
contents: [{ id: "pricing", name: "Pricing page", content_type: "page" }],
});
oaiq("measure", "contents_viewed", {
type: "contents",
contents: [
{ id: "sku_123", name: "Starter bundle", content_type: "product" },
],
});
// Ticaret olayları (contents şekli)
oaiq("measure", "items_added", {
type: "contents",
amount: 2599,
currency: "USD",
contents: [
{
id: "sku_123",
name: "Starter bundle",
content_type: "product",
quantity: 1,
amount: 2599,
currency: "USD",
},
],
});
oaiq("measure", "order_created", {
type: "contents",
amount: 2599,
currency: "USD",
contents: [
{
id: "sku_123",
name: "Starter bundle",
content_type: "product",
quantity: 1,
},
],
});
// Lead ve kayıt (customer_action şekli)
oaiq("measure", "lead_created", { type: "customer_action" });
// Abonelik ve deneme (plan_enrollment şekli)
oaiq("measure", "subscription_created", {
type: "plan_enrollment",
plan_id: "pro_monthly",
amount: 2000,
currency: "USD",
});
oaiq("measure", "trial_started", {
type: "plan_enrollment",
plan_id: "pro_trial",
});Parasal değer her zaman tam sayı ve ISO 4217 minor units biçimindedir; amount varsa currency zorunludur. Örneğin 25,99 dolar 2599 olarak gönderilir2.
Custom Event
Taksonomide olmayan bir eylem için custom kullanılır ve options nesnesine custom_event_name eklenir1.
oaiq(
"measure",
"custom",
{ type: "custom" },
{ custom_event_name: "quote_requested" },
);Custom isim kuralları: 1-64 karakter; harf, rakam, alt çizgi, tire; harf ya da rakamla başlayıp biter; bir standart event adını tekrar edemez; tutarlılık için küçük harf önerilir1.
event_id ile Sunucu Tarafına Köprü
Aynı dönüşüm hem pixel hem sunucu Conversions API’sinden gönderilecekse, çift sayımı önlemek için pixel tarafında options.event_id verilir ve bu değer sunucudaki id ile aynı tutulur; iki tarafta da aynı Pixel ID kullanılır1.
oaiq(
"measure",
"order_created",
{ type: "contents", amount: 2599, currency: "USD" },
{ event_id: "order_12345" },
);Burada event_id yalnızca eşleşmeyi kurar; tekilleştirmenin nasıl çalıştığı ve sunucu tarafının kurulumu ayrı yazıların konusu.
SDK’nın Otomatik Yaptıkları
Pixel, kurulumdan sonra birkaç işi kendiliğinden halleder1:
opprefkimliğini açılış sayfası URL’inden yakalar.- Bu kimliği ilk taraf
__opprefçerezinde saklar, sonraki sayfa görüntülemelerinde tekrar kullanır. - Geçerli sayfa kaynağını
source_urlolarak ekler. - Her olayı zaman damgalar ve yakın zamanlı
measureçağrılarını gruplar.
Bu otomatik davranışlar sayesinde tıklama sonrası kimlik takibi ve toplu gönderim için ek kod yazmaya gerek kalmaz.
Test ve Sık Hatalar
Kurulumu doğrularken birkaç noktaya dikkat1:
- Test boyunca
debug: trueaçık tut, konsol loglarını izle. amountvequantitydeğerlerini tam sayı gönder, metin değil.contents[]içine yalnızca dokümante alanları koy.- Tarayıcıda her zaman pixel’i kullan; sunucu Conversions API’sini sayfa kodundan çağırma, sunucudan çağır.
Pixel tek başına yeterli mi?
Tarayıcı pixel’i kurulumun ilk adımı, ama tek başına ölçümün tamamı değil. Reklam engelleyici, consent reddi ve çerez kısıtları client-side veriyi eksiltir. Kritik dönüşümleri ayrıca sunucu Conversions API’sinden göndermek, bu boşluğu kapatır.
Sonraki Adımlar
Tarayıcı tarafı çalışınca sıra, kritik dönüşümleri sunucudan da göndermeye ve iki katmanı dedup ile uzlaştırmaya gelir. Pixel kurulumu, ölçüm mimarisinin yalnızca ilk katmanı; sunucu tarafı ve tekilleştirme, ölçümü eksik örneklemden bir sayıma taşıyan parçalar.
Footnotes
-
JavaScript Pixel (OpenAI Developers) — oaiq snippet ve bzrcdn.openai.com kaynağı, init ile pixelId ve istek kapsamlı user alanları, measure argüman sırası, standart ve custom event örnekleri, custom_event_name kuralları, event_id ile browser/server dedup, otomatik oppref/
__oppref/source_url/batching, “Always use the pixel on the browser. Do not call the server conversions API directly from page code.” ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 -
Supported events (OpenAI Developers) — standart event taksonomisi, data şekilleri (contents/customer_action/plan_enrollment), minor units kuralı (“
12999for $129.99”) veamountvarsacurrencyzorunluluğu. ↩ ↩2
- 01 Pixel kurulumu üç adım: snippet'i head'e ekle, oaiq('init') ile Pixel ID ver, dönüşümde oaiq('measure') çağır.
- 02 Kullanıcı eşleştirme alanları (email_sha256 gibi) init'e eklenir, tekil measure çağrılarına değil; hepsi opsiyonel ve hash'li.
- 03 measure verisinin type alanı event şekline uyar: contents, customer_action, plan_enrollment. amount varsa currency zorunlu, değerler tam sayı.
- 04 Sunucu Conversions API ile dedup için pixel'de options.event_id verilir ve sunucudaki id ile aynı tutulur; pixel her zaman tarayıcıda, API sunucudan çağrılır.
+ OpenAI Ads pixel'i nereye eklenir?
Snippet, dönüşüm yakalanan her sayfanın <head> bölümüne, mümkün olduğunca üste eklenir. Erken gerçekleşen dönüşümlerin kaybolmaması için pixel'in sayfanın en başında yüklenmesi önemli. Pixel ID, Ads Manager'ın conversions sekmesinden alınır.
+ Kullanıcı eşleştirme verisi nereye konur?
Kullanıcı verisi istek kapsamlıdır ve oaiq('init') çağrısına eklenir, tekil oaiq('measure') çağrılarına değil. Tüm alanlar opsiyoneldir; yalnızca elde olan gönderilir. Kullanıcı verisi sonradan geldiyse (örneğin giriş sonrası) init tekrar çağrılır, pixelId ilk init'ten sonra atlanabilir.
+ Standart event ile custom event arasındaki fark nedir?
Standart event'ler taksonomideki hazır isimlerdir (page_viewed, order_created gibi) ve tipe uygun bir data şekli kullanır. Custom event, taksonomide olmayan bir eylem için 'custom' adıyla gönderilir ve options nesnesinde custom_event_name gerektirir; isim 1-64 karakter, küçük harf, harf/rakam/alt çizgi/tire olur ve bir standart event adını tekrar edemez.
+ Pixel ile sunucu Conversions API'sini birlikte mi kullanmalı?
Evet, ama her birini doğru yerden çağırarak. Pixel her zaman tarayıcıda kullanılır; sunucu Conversions API'si sayfa kodundan değil sunucudan çağrılır. Aynı dönüşüm iki taraftan da gönderiliyorsa, pixel'de options.event_id ile sunucudaki id aynı tutulur ve aynı Pixel ID kullanılır, böylece dedup çalışır.