Conversions API (CAPI), e-ticaret sitenizdeki satın alma, sepete ekleme gibi olayları tarayıcı yerine doğrudan sunucunuzdan Meta’ya gönderen bir ölçüm bağlantısıdır. “Conversions api nedir?” sorusunun kısa cevabı şu: Pixel’in reklam engelleyiciler, çerez kısıtlamaları ve iOS gizlilik ayarları yüzünden kaçırdığı dönüşümleri yakalamaya yarayan, Pixel’le birlikte çalışan ikinci bir veri kanalıdır.
Bu yazıda CAPI’nin ne işe yaradığını, hangi kurulum yolunun size uygun olduğunu ve hesaplarda en sık gördüğümüz hataları anlatıyoruz.
Conversions API nedir, Pixel’den farkı ne?
Meta Pixel, sitenize eklenen bir JavaScript kodudur ve ziyaretçinin tarayıcısında çalışır. Ziyaretçi ürün sayfasına girdiğinde, sepete eklediğinde ya da ödeme yaptığında bu kod Meta’ya sinyal yollar. Sorun şu ki tarayıcı her zaman güvenilir bir ortam değil.
Conversions API ise aynı olayı sitenizin sunucusundan, ya da kullandığınız e-ticaret altyapısının sunucusundan gönderir. Ziyaretçinin tarayıcısında ne olduğu bu gönderimi etkilemez. Bu yüzden ikisi rakip değil, birbirini tamamlayan iki kanal olarak düşünülmeli.
| Özellik | Meta Pixel | Conversions API |
|---|---|---|
| Nerede çalışır? | Ziyaretçinin tarayıcısında | Sunucuda |
| Reklam engelleyiciden etkilenir mi? | Evet | Hayır |
| Çerez ve tarayıcı kısıtlamaları | Doğrudan etkiler | Etkisi çok daha az |
| Kurulum zorluğu | Kolay | Yönteme göre kolay ile orta arası |
| Gönderebileceği veri | Tarayıcıda olanlar | Sipariş, müşteri ve CRM verileri dahil |
| Önerilen kullanım | CAPI ile birlikte | Pixel ile birlikte |
Pixel’in temel kurulumunu henüz tamamlamadıysanız önce Facebook Pixel kurulumu rehberimize göz atmanızı öneririz. CAPI, sağlam bir Pixel kurulumunun üstüne inşa edilir.
E-ticaret sitesi neden Conversions API’ye ihtiyaç duyar?
Pixel tek başına çalıştığında bazı satın almalar Meta’ya hiç ulaşmaz. Bunun birkaç yaygın nedeni var:
- Reklam engelleyiciler: Masaüstünde ve bazı mobil tarayıcılarda Pixel kodu tamamen engellenebilir.
- iOS ve tarayıcı gizlilik ayarları: Uygulama izleme izni vermeyen kullanıcılar ve Safari gibi tarayıcıların çerez kısıtlamaları, ziyaretçiyi reklam tıklamasıyla eşleştirmeyi zorlaştırır.
- Ödeme sayfası yönlendirmeleri: iyzico, PayTR gibi ödeme altyapılarında 3D Secure adımından sonra kullanıcı teşekkür sayfasına dönmezse Purchase olayı tetiklenmeyebilir.
- Yavaş bağlantı ve erken kapanan sekmeler: Kullanıcı sayfa tamamen yüklenmeden çıkarsa Pixel olayı gitmeyebilir.
Kaçan her dönüşüm iki şekilde zarar verir. Birincisi, raporlarınızda ROAS olduğundan düşük görünür ve iyi çalışan kampanyaları yanlışlıkla kapatabilirsiniz. İkincisi, Meta’nın algoritması daha az satın alma sinyaliyle öğrenir; bu da hedeflemenin ve teklif stratejisinin zayıflaması demek. ROAS’ı doğru okumak için ROAS ve kârlılık hesabı yazımıza da bakabilirsiniz.
Conversions API’nin e-ticarete sağladığı faydalar
Hesaplarda CAPI’yi doğru kurduğumuzda genellikle şu iyileşmeleri görüyoruz:
- Daha eksiksiz dönüşüm verisi: Pixel’in kaçırdığı satın almaların önemli bir kısmı raporlara geri döner. Oran siteye, kitleye ve cihaz dağılımına göre değişir.
- Daha iyi eşleşme: Sunucudan e-posta, telefon gibi hash’lenmiş müşteri bilgileri gönderildiğinde Meta, satın almayı reklamı gören kişiyle daha isabetli eşleştirir.
- Algoritmanın daha iyi öğrenmesi: Advantage+ gibi otomasyona dayalı kampanyalar sinyalle beslenir. Veri arttıkça optimizasyon daha istikrarlı hale gelir. Bu konuyu Advantage+ Shopping kampanyaları yazımızda ayrıntılı ele aldık.
- Sitede olmayan olayları gönderebilme: Telefonla tamamlanan siparişler, iade sonrası net satışlar ya da CRM’deki tekrar alımlar gibi tarayıcıda gerçekleşmeyen olaylar da gönderilebilir.
- Daha doğru yeniden pazarlama kitleleri: Sepete ekleyen veya satın alan kişiler daha eksiksiz yakalandığı için özel hedef kitleler daha isabetli dolar.
Şunu da açıkça söyleyelim: CAPI reklamlarınızı kendiliğinden daha kârlı yapmaz. Yaptığı şey, ölçümü gerçeğe yaklaştırmak ve algoritmaya daha temiz veri vermektir. Kreatif, teklif ve ürün tarafı zayıfsa sonuç değişmez.
Conversions API nasıl kurulur? 4 yöntem
Kurulum yolu, sitenizin hangi altyapıda çalıştığına ve teknik kaynağınıza göre değişir.
1. Altyapı entegrasyonu (en kolay yol)
Shopify’da Meta’nın resmi Facebook & Instagram uygulaması, WooCommerce’te ise Facebook for WooCommerce eklentisi CAPI’yi birkaç tıkla açar. Türkiye’de kullanılan hazır e-ticaret altyapılarının bir kısmı da panelde Conversions API desteği sunuyor; altyapı sağlayıcınızın ayarlarında “Conversions API” veya “sunucu taraflı izleme” seçeneğini arayın. Teknik bilgi gerektirmez, ancak hangi parametrelerin gönderildiği üzerinde kontrolünüz sınırlıdır.
2. Conversions API Gateway
Meta’nın sunduğu, kendi bulut hesabınızda (örneğin AWS) çalışan hazır bir sunucu çözümüdür. Etkinlik Yöneticisi üzerinden yönlendirmeli şekilde kurulur ve Pixel olaylarını otomatik olarak sunucu tarafına da kopyalar. Kod yazmanız gerekmez ama aylık bir bulut sunucu maliyeti oluşur.
3. Sunucu taraflı Google Tag Manager
Zaten GTM kullanan ve Google Ads, GA4 gibi diğer platformları da sunucu tarafına taşımak isteyen markalar için esnek bir yoldur. Sunucu konteyneri barındırma maliyeti ve kurulum için teknik destek gerekir. Avantajı, tüm ölçüm altyapısını tek noktadan yönetebilmenizdir.
4. Doğrudan API entegrasyonu
Özel yazılmış bir e-ticaret sitesi veya kendi CRM’iniz varsa geliştirici ekibiniz olayları doğrudan Meta’nın API’sine gönderebilir. En fazla kontrolü sağlar, en fazla geliştirme emeği de bunu ister.
| Yöntem | Kimin için uygun? | Teknik ihtiyaç | Ek maliyet |
|---|---|---|---|
| Altyapı entegrasyonu | Shopify, WooCommerce, hazır altyapılar | Düşük | Genellikle yok |
| CAPI Gateway | Kod yazmadan sunucu kurulumu isteyenler | Düşük–orta | Aylık bulut maliyeti |
| Sunucu taraflı GTM | Çok platformlu ölçüm yapanlar | Orta | Sunucu barındırma |
| Doğrudan API | Özel yazılım ve CRM kullananlar | Yüksek | Geliştirme emeği |
Hangi yolu seçerseniz seçin, teknik ayrıntılar ve parametre listesi için Meta’nın resmi Conversions API geliştirici belgeleri temel kaynaktır.
Conversions API kurulumu adım adım: WooCommerce örneği
Türkiye’de çalıştığımız e-ticaret sitelerinin önemli bir kısmı WooCommerce üzerinde. Resmi eklentiyle kurulum genel hatlarıyla şöyle ilerliyor (menü adları sürüme göre küçük farklılıklar gösterebilir):
- Hazırlık: Meta Business hesabınızda işletme yöneticisi yetkisine sahip olduğunuzdan ve sitenizde kullanılan Pixel’in (veri kümesinin) bu işletmeye bağlı olduğundan emin olun.
- Eklentiyi kurun: WordPress panelinde Facebook for WooCommerce eklentisini yükleyip etkinleştirin.
- Hesabı bağlayın: Eklenti ayarlarından Meta hesabınızla bağlantı kurun; işletme, reklam hesabı ve Pixel seçimini doğru yapın.
- Sunucu olaylarını açın: Bağlantı tamamlandığında eklentinin Conversions API gönderimini etkinleştirdiğini ayarlardan kontrol edin.
- Eski kodları temizleyin: Temaya elle eklenmiş Pixel kodu, başka bir eklenti veya GTM üzerinden aynı Pixel çalışıyorsa bunları kaldırın ya da devre dışı bırakın. Aksi halde olaylar birden fazla kez gider.
- Test edin: Etkinlik Yöneticisi’ndeki test olayları ekranında bir deneme siparişi verin ve Purchase olayının hem tarayıcıdan hem sunucudan geldiğini görün.
Shopify tarafında süreç daha da kısa: Facebook & Instagram uygulamasını kurup veri paylaşım ayarını en kapsamlı seviyeye getirdiğinizde sunucu taraflı gönderim devreye girer. Özel yazılım kullanan sitelerde ise aynı adımları geliştirici ekibinizle doğrudan API üzerinden uygulamanız gerekir.
Kurulum sırasında en çok zaman kaybettiren şey, eski kurulumlardan kalan kodlar. Bu yüzden işe başlamadan önce sitede hangi ölçüm kodlarının çalıştığını bir tarayıcı eklentisiyle listelemenizi öneriyoruz.
Conversions API ile hangi olaylar gönderilmeli?
Her olayı sunucudan göndermek gerekmez; önemli olan satın alma yolculuğundaki ana adımları eksiksiz göndermek. E-ticaret için önerdiğimiz temel set:
| Olay | Ne zaman tetiklenir? | Mutlaka gönderilmesi gereken parametreler |
|---|---|---|
| ViewContent | Ürün sayfası görüntülendiğinde | content_ids, value, currency |
| AddToCart | Ürün sepete eklendiğinde | content_ids, value, currency |
| InitiateCheckout | Ödeme adımına geçildiğinde | value, currency, num_items |
| AddPaymentInfo | Ödeme bilgisi girildiğinde | value, currency |
| Purchase | Sipariş tamamlandığında | event_id, value, currency, content_ids, müşteri bilgileri |
| Lead | Form gönderildiğinde (hizmet işletmeleri) | event_id, müşteri bilgileri |
Burada iki noktaya dikkat edin. Birincisi, content_ids değerleri katalogdaki ürün kimlikleriyle aynı olmalı; aksi halde dinamik ürün reklamları doğru ürünü gösteremez. İkincisi, value alanında KDV dahil mi hariç mi gönderdiğinizi bir kez belirleyip tüm olaylarda aynı kuralı uygulayın. Bu tercih, ROAS’ı nasıl yorumlayacağınızı doğrudan etkiler.
Satın alma sonrası olaylar da gönderilebilir. Örneğin iade edilen siparişleri veya telefonla tamamlanan satışları CRM’den sunucu üzerinden göndermek, raporları gerçeğe yaklaştırır. Bu tür gelişmiş kullanımlar genellikle doğrudan API veya sunucu taraflı GTM gerektirir.
Tekilleştirme: aynı satışın iki kez sayılmaması
Pixel ve CAPI aynı satın almayı birlikte gönderdiğinde Meta’nın bunları tek olay olarak sayması gerekir. Buna tekilleştirme (deduplication) deniyor ve kurulumun en kritik adımıdır.
Meta, iki olayı şu bilgilerle eşleştirir:
- event_name: Her iki tarafta aynı olay adı (örneğin Purchase).
- event_id: Her iki tarafta aynı benzersiz kimlik. E-ticarette genellikle sipariş numarası kullanılır.
Tekilleştirme çalışmazsa satın almalar iki kez sayılır, ROAS olduğundan yüksek görünür ve bütçe kararları yanlış verilir. Örnek: Gerçekte 50 satış yaptığınız bir haftada raporda 80–90 satış görüyorsanız ilk kontrol etmeniz gereken yer burasıdır.
Etkinlik eşleşme kalitesi nasıl yükseltilir?
Etkinlik Yöneticisi’nde her olay için 0–10 arası bir “Etkinlik eşleşme kalitesi” (Event Match Quality) puanı görürsünüz. Bu puan, gönderdiğiniz müşteri bilgilerinin Meta kullanıcılarıyla ne kadar iyi eşleştiğini gösterir.
Puanı yükseltmek için sunucu olaylarına şu parametreleri eklemek gerekir:
- E-posta adresi ve telefon numarası (SHA-256 ile hash’lenmiş; telefon ülke koduyla, örneğin 90 ile başlamalı)
- Ad, soyad, şehir, posta kodu
- fbp ve fbc çerez değerleri (tarayıcıdan alınıp sunucu olayına eklenir)
- Kullanıcının IP adresi ve tarayıcı bilgisi (user agent)
- Varsa üye kimliği (external_id)
Satın alma olayında bu bilgilerin çoğu zaten sipariş formunda bulunduğu için yüksek puan almak görece kolaydır. Ürün görüntüleme gibi üst huni olaylarında puanın daha düşük olması normaldir.
Kurulumdan sonra kontrol listesi ve sık hatalar
Kurulumu yaptıktan sonra şu adımları sırayla kontrol etmenizi öneririz:
- Etkinlik Yöneticisi’nde Purchase olayının hem “Tarayıcı” hem “Sunucu” kaynağından geldiğini görün.
- “Test olayları” sekmesinden bir deneme siparişi verip iki kaynağın da düştüğünü ve tekilleştirildiğini doğrulayın.
- Satın alma olayında değer (value) ve para birimi (currency: TRY) parametrelerinin doğru geldiğini kontrol edin.
- Eşleşme kalitesi puanını ve Meta’nın önerdiği eksik parametreleri inceleyin.
- Bir hafta sonra Meta’daki satın alma sayısını sitenizin panelindeki sipariş sayısıyla karşılaştırın.
Hesaplarda en sık karşılaştığımız hatalar:
- event_id uyuşmazlığı: Pixel sipariş numarasını, sunucu ise farklı bir kimliği gönderiyor; sonuç çift sayım.
- Para birimi hatası: TL yerine USD gönderilmesi veya KDV dahil/hariç tutarların karışması.
- İki ayrı entegrasyon: Hem eklenti hem GTM üzerinden CAPI açık kaldığı için aynı olayın üç kez gitmesi.
- Gecikmeli gönderim: Meta, olay zamanından 7 günden eski olayları kabul etmez; toplu gönderimlerde bu sınır aşılmamalı.
- İzin yapısıyla çelişki: Çerez onayı vermeyen kullanıcının verisinin sunucudan yine de gönderilmesi KVKK açısından risk oluşturur. Aydınlatma metninizi ve onay yapınızı kurulumla birlikte gözden geçirin.
Ölçüm altyapısı doğru kurulduğunda kampanya kararları çok daha sağlam bir zemine oturur. Meta Ads hizmetimizde kampanya yönetimine başlamadan önce Pixel ve CAPI kurulumunu bu kontrol listesiyle denetliyoruz.
Kısaca
- Conversions API, dönüşüm olaylarını sunucudan Meta’ya gönderir ve Pixel’in kaçırdığı satışları yakalar.
- Pixel’i kaldırmayın; doğru yapı ikisinin birlikte çalışması ve aynı event_id ile tekilleştirilmesidir.
- Shopify ve WooCommerce’te resmi entegrasyon en hızlı yol; daha fazla kontrol için CAPI Gateway veya sunucu taraflı GTM tercih edilebilir.
- Eşleşme kalitesini yükseltmek için e-posta, telefon ve fbp/fbc bilgilerini hash’lenmiş olarak eksiksiz gönderin.
- Kurulumdan sonra Meta’daki satın alma sayısını gerçek sipariş sayınızla mutlaka karşılaştırın.
Ölçüm kurulumunuza birlikte bakmak isterseniz ücretsiz analiz talep edebilirsiniz.