Dönüşüm API'si Nedir? Meta Pixel'den Farkı ve Kurulumu

Dönüşüm API'si (Conversions API), web sitesindeki dönüşümleri tarayıcı yerine sunucudan Meta'ya bildiren bir bağlantıdır. Meta Pixel'in yerine değil, yanına kurulur ve Pixel'in kaçırdığı olayları tamamlar. Aşağıda Pixel'den farkını, dört kurulum yolunu ve olay tekilleştirmeyi anlatıyoruz. Olay eşleşme kalitesini, hash'lenen müşteri bilgilerini ve çerez onayıyla ilişkisini de ele aldık. Kendi sitemizde doğrudan kodla kurduğumuz yapıyı örnek gösteriyoruz.

Dönüşüm API'si nedir, nasıl çalışır?

Dönüşüm API'si, sitenin sunucusunun Meta'ya HTTP isteğiyle olay gönderdiği bir arayüzdür. İstek Pixel kimliğine bağlı bir uca gider ve olay Pixel'den gelmiş gibi işlenir. Ölçümde, raporlamada ve kampanya iyileştirmede aynı yeri tutar.

Meta'nın geliştirici belgelerine göre istek, Graph API'deki events ucuna POST olarak gönderilir. Adreste API sürümü ve Pixel kimliği yer alır. Yetki için Olay Yöneticisi'nden üretilen bir erişim belirteci kullanılır. Bir istekte en fazla 1.000 olay gidebilir. Olay zamanı en fazla 7 gün geriye yazılabilir; daha eskisi bütün isteği reddettirir.

Web olayında şu alanlar bulunur:

• event_name: olayın adı, örneğin Lead ya da Purchase.
• event_time: olayın saniye cinsinden Unix zamanı.
• action_source: olayın kaynağı; site için website.
• event_source_url: olayın gerçekleştiği sayfanın adresi, web olayında zorunlu.
• user_data: ziyaretçiyi eşleştirmeye yarayan müşteri bilgileri.
• event_id: tekilleştirme için olay kimliği; zorunlu değil, ama önerilir.

Meta, olayların gerçek zamanlı ya da ona yakın gönderilmesini önerir. Belgelere göre kampanya performansı için en iyi sonuç böyle alınır.

Meta Pixel'den farkı nedir?

Pixel olayı ziyaretçinin tarayıcısından, Dönüşüm API'si sitenin sunucusundan gönderir. Reklam engelleyici ya da kopan bir bağlantı Pixel'i durdurabilir; sunucudaki gönderimi durduramaz. Meta bu yüzden ikisini birlikte, aynı olaylarla kullanmayı önerir.

Pixel'in kurulumunu ve çerez onayına bağlanmasını Meta Pixel kurulum rehberimizde anlattık. Aşağıdaki tablo yalnızca iki kanalın farkını gösteriyor.

Sunucu tarafı tek başına da çalışabilir. Ama sayfa görüntüleme gibi tarayıcıda olan işler Pixel'le çok daha kolay yakalanır. (Bizim tercihimiz, sayfa görüntülemeyi Pixel'e bırakmak, form ve kayıt gibi dönüşümleri sunucudan da göndermek.)

Hangi kurulum yolu kime uyar?

Dört yol var: iş ortağı entegrasyonu, Conversions API Gateway, sunucu taraflı etiket yöneticisi ve doğrudan kod. Aralarındaki fark emek, süren maliyet ve denetimdir. Seçimi sitenin altyapısı ve ekipte geliştirici olup olmadığı belirler.

İş ortağı entegrasyonu nasıl çalışır?

Site bir e-ticaret paketi ya da içerik yönetim sistemiyle çalışıyorsa en hızlı yol budur. Pixel iş ortağıyla paylaşılır ve olayları iş ortağı gönderir. Kod yazmak gerekmez.

Meta'nın belgesine göre iş ortağı, kendi sistem kullanıcısını Pixel'e atar ve bir erişim belirteci üretir. Hangi olayın hangi alanlarla gideceğine iş ortağı karar verir. Kurulumdan sonra tekilleştirme oranına ve eşleşme kalitesine bakmak yine site sahibine düşer.

Conversions API Gateway ne sunar?

Gateway, Olay Yöneticisi'nden kurulan ve geliştirici gerektirmeyen bir ara katmandır. Tarayıcıdan gelen olayları alır ve Dönüşüm API'sine iletir. Tekilleştirme için olay kimliğini kendisi üretip iki kanala taşır.

Ücret Meta'ya değil, bulut sağlayıcısına ya da iş ortağına ödenir. Meta'ya göre Gateway, AWS ya da Google Cloud üzerinde çalışır ve bu sağlayıcılardan birinde hesap ister. Tek kurulum birden çok Pixel'i ve alan adını taşıyabilir. Olayı tarayıcıdan aldığı için Pixel yüklenmeyen ziyaretçide sunucu olayı da oluşmaz.

Sunucu taraflı etiket yöneticisi ne zaman mantıklıdır?

Analiz, Google Ads ve Meta etiketlerini tek bir sunucudan beslemek isteyen siteler için mantıklıdır. Tarayıcı veriyi bir etiketleme sunucusuna yollar. Sunucu da her platforma kendi biçiminde iletir.

Etiketleme sunucusunun bir işletme yükü vardır. Google, veri kaybı riskini azaltmak için en az 2 sunucu çalıştırmayı önerir. Her sunucu ayrı bir aylık bulut maliyeti demektir. Google, etiketleme sunucusunun sitenin kendi alan adı altında çalışmasını da önerir.

Doğrudan kodla gönderim kime uyar?

Siteyi kendi yazılımıyla yöneten ve geliştiricisi olan işletmeye uyar. Gönderilen alanlar, onay kuralı ve hata kaydı tamamen elinizdedir. Karşılığında API sürüm değişikliklerini izlemek de size kalır.

Meta, Marketing API sürümlerini belirli aralıklarla kapatır. Önceki sürüm, yenisi çıktıktan sonra en az 90 gün desteklenir. Değişiklik günlüğüne göre Marketing API'nin v24.0 sürümü 6 Ekim 2026'da kapandı. Kendi sitemiz olayları v25.0 ile gönderiyor. Bu tür bağlantıları özel yazılım geliştirme hizmetimiz kapsamında kuruyoruz.

Olay tekilleştirme nasıl çalışır?

Aynı form hem Pixel'den hem sunucudan bildirilince Meta iki olay alır. Tekilleştirme, Meta'nın bu ikisini tek olay saymasıdır. Bunun için olay adı ve olay kimliği iki kanalda aynı olmalıdır.

Pixel tarafında kimlik eventID, sunucu tarafında event_id alanıyla gider. Meta, aynı kimlikli olayları ilk olayın gelişinden sonraki 48 saat içinde birleştirir. İçerikleri belirgin biçimde farklı değilse genellikle önce geleni tutar. Kimlik, sipariş numarası gibi gerçek bir değer ya da rastgele bir dize olabilir.

Belgelenmiş ikinci bir yol daha var: olay adıyla birlikte fbp ya da external_id eşleşmesi. Bu yolda sunucu olayı önce gelirse ve 48 saat içinde tarayıcı olayı yoksa sunucu olayı atılmaz. Sonradan gelen aynı tarayıcı olayı da sayılır. Meta'nın önerdiği yol bu yüzden event_id eşleşmesidir.

Kendi sitemizde kimliği tarayıcı üretiyor ve form verisiyle sunucuya gönderiyor. Sunucu bu kimliği event_id alanına yazıyor. Form başarıyla kaydedilince Pixel de Lead olayını aynı kimlikle gönderiyor.

Olay eşleşme kalitesi neyi ölçer?

Olay eşleşme kalitesi, sunucu olayındaki müşteri bilgilerinin bir Meta hesabıyla ne kadar iyi eşleşebildiğini gösteren puandır. Puan 10 üzerinden verilir ve şimdilik yalnızca web olaylarında görünür. Meta genellikle 6,0 ve üstünü hedeflemeyi önerir.

Meta'ya göre puanı en çok e-posta, IP adresi, ad-soyad ve telefon yükseltir. fbp ve fbc değerleri de eşleşmeye katkı verir, ama düzenli tazelenmeleri gerekir. Teklif formunda e-posta sorulmuyorsa telefon ve ad belirleyici olur. Kendi teklif formumuz telefon, ad ve ülke bilgisini gönderiyor.

Puan, Olay Yöneticisi'nde Pixel'in genel bakış sayfasında görünür. Düşükse önce hangi alanların hiç gönderilmediğine, sonra biçimlerine bakmak gerekir.

Hangi müşteri bilgileri hash'lenir?

E-posta, telefon, ad, soyad, şehir, posta kodu ve ülke gibi kişisel alanlar SHA-256 ile hash'lenerek gönderilir. IP adresi, tarayıcı bilgisi, fbp ve fbc ise hash'lenmez. Hash'ten önce her alan Meta'nın istediği biçime getirilmelidir.

Hash, bir değeri geri çevrilemeyen sabit uzunlukta bir dizeye dönüştürür. Meta aynı işlemi kendi verisine uygular ve iki dizeyi karşılaştırır. Tek bir büyük harf ya da boşluk bambaşka bir dize üretir ve eşleşme kaybolur.

• E-posta: baştaki ve sondaki boşluk silinir, tamamı küçük harfe çevrilir.
• Telefon: yalnızca rakam kalır ve ülke koduyla başlar.
• Ad ve soyad: küçük harf, noktalama yok.
• Ülke: ISO 3166-1 iki harfli kod, küçük harfle; Türkiye için tr.

Türkiye'deki telefonlar ayrı dikkat ister. Formda 0532 diye başlayan numara, kodumuzda 90532 ile başlayacak biçime çevriliyor. Doğrudan 5 ile yazılan on haneli numaraya da 90 ekleniyor. Türkçe harflerde ise büyük İ ve I önce elle çevriliyor, sonra küçük harfe geçiliyor.

fbc değeri fb.1.[zaman].[fbclid] biçimindedir. Pixel'in _fbc çerezi yoksa bu değer, reklam tıklamasında adrese eklenen fbclid parametresinden kurulabilir. Sunucumuz çerez gelmediğinde bunu yapıyor.

Çerez onayı reddedilirse sunucu ne gönderir?

Bizim kurulumumuzda hiçbir şey göndermez. Ziyaretçi pazarlama çerezlerini reddettiyse ne Pixel yüklenir ne de sunucu Meta'ya istek atar. Form verisinde onay bilgisi bulunmaz ve sunucu olay kurmaz.

Sunucu tarafını onaydan bağımsız saymak bize göre yanlıştır. Olay tarayıcıdan gitmese de telefon ve ad gibi kişisel veriler taşır. Hash'lenmiş olsalar da Meta bu değerleri bir hesapla eşleştirmek için kullanır. (Aydınlatma metni ve yurt dışına aktarım dayanağı için hukuk danışmanınızın görüşünü almanızı öneririz.)

Onay kararını sunucumuz iki yerden okuyor. Site, onay veren ziyaretçinin form verisine bir onay alanı ekliyor. Form verisi olmayan isteklerde, örneğin Google ile üyelik dönüşünde, onay çerezine bakılıyor. Çerezdeki değer pazarlama kategorisi için 1 değilse olay kurulmuyor.

Doğrudan kodla kurulumu sitemizde nasıl yaptık?

Sitemiz Next.js, sunucu tarafı PHP ile çalışıyor ve Dönüşüm API'si çağrısını PHP tarafında kendimiz yazdık. Teklif formu Lead, yeni üyelik CompleteRegistration olarak gidiyor. Bülten aboneliği de sunucudan Lead olarak bildiriliyor.

1. Ziyaretçi onay verdiyse tarayıcı rastgele bir olay kimliği üretir.
2. Kimlik, _fbp ve _fbc değerleriyle birlikte form verisine eklenir.
3. Sunucu formu kaydeder ve ziyaretçiye yanıtı hemen döner.
4. Kayıt başarılıysa Pixel, Lead olayını aynı kimlikle gönderir.
5. Yanıt gittikten sonra sunucu olayı v25.0 sürümüyle Meta'ya iletir.
6. Sonuç kayda yazılır; kayıtta kişisel veri yoktur, 30 günden eskisi silinir.

Meta'ya giden istek, bağlantı için 5 saniye, toplamda 15 saniye bekler. Ziyaretçi bu süreyi görmez, çünkü yanıtını çoktan almıştır. Gönderim hata verirse sunucu günlüğüne yazılır; form kaydı etkilenmez.

Ayarları yönetim panelimizden yapıyoruz: Pixel kimliği, erişim belirteci ve test olay kodu. Erişim belirteci panele geri gönderilmez, yalnızca kayıtlı olup olmadığı görünür. Paneldeki deneme düğmesi dönüşüm sayılan bir olay değil, PageView gönderir. Böylece deneme reklam sonuçlarına karışmaz.

Kurulum nasıl test edilir?

Test, Olay Yöneticisi'ndeki Olayları Test Edin ekranıyla yapılır. Sunucu isteğine test_event_code alanı eklenir ve olaylar o ekranda görünür. Ardından tekilleştirme oranına ve eşleşme kalitesine bakılır.

1. Olay Yöneticisi'nden test kodunu alın ve sunucu ayarına yazın.
2. Gizli pencerede çerezleri kabul edip formu deneme verisiyle gönderin.
3. Test ekranında Lead olayının tarayıcıdan ve sunucudan aynı kimlikle geldiğini görün.
4. Çerezleri reddedip formu yeniden gönderin; ekrana hiçbir olay düşmemeli.
5. Test kodunu kaldırın ve 20 dakika sonra genel bakış sayfasındaki sayılara bakın.

Test kodunun bir yan etkisi var. Meta'ya göre test kodlu olaylar atılmaz; Olay Yöneticisi'ne akar ve ölçümde kullanılır. Canlıya geçerken kodu kaldırmak bu yüzden şarttır. Tekilleştirme oranı da olay ayrıntılarındaki tekilleştirme sekmesinde görünür; oran ne kadar yüksekse o kadar iyidir.

Ölçüm kurulumunu reklam yönetimiyle birlikte yürütmek isterseniz Meta reklam yönetimi hizmetimiz Pixel ile Dönüşüm API'sini birlikte kapsar.