Meta Conversions API (CAPI) Kurulumu: Tekilleştirme ve EMQ Rehberi

Conversions API nedir ve Pixel'den farkı ne?

Conversions API (Dönüşümler API'si), satın alma, sepete ekleme veya form gibi olayları ziyaretçinin tarayıcısı yerine sizin sunucunuzdan Meta'ya gönderir. Pixel tarayıcıda çalışır; reklam engelleyici, çerez kısıtı ya da yavaş yüklenen bir sayfa olayı yolda kaybettirebilir. Sunucudan sunucuya giden olayları ise tarayıcı tarafındaki engelleyiciler durduramaz.

Burada sık yapılan hata CAPI'yi Pixel'in yerine geçen bir şey sanmaktır. Meta'nın önerdiği yapı yedekli kurulumdur: aynı olay hem Pixel'den hem sunucudan gelir, Meta ikisini eşleştirip tek sayar. Böylece tarayıcı olayı kaçırdığında sunucu olayı boşluğu doldurur, sunucu olayı eksik bilgiyle geldiğinde Pixel'in taşıdığı çerez bilgisi (fbp, fbc) eşleşmeye yardımcı olur.

Pixel ve CAPI'nin rakamları neden Shopify veya GA4 raporlarından farklı çıktığını merak ediyorsanız Shopify, Meta ve GA4 rakamlarının neden tutmadığını anlatan yazımıza da bakın.

CAPI'yi hangi yöntemle kurmalısınız?

Hazır altyapı (Shopify, ikas, Ticimax vb.) kullanıyorsanız önce platformun kendi entegrasyonunu deneyin; özel yazılım sitelerde Conversions API Gateway veya doğrudan entegrasyon devreye girer. Seçimi belirleyen şey teknik ekibiniz ve olayları ne kadar özelleştirmek istediğinizdir.

Karar kuralı basit: altyapınızda Meta için “Dönüşüm API” veya “Erişim Jetonu” alanı varsa oradan başlayın. Yoksa ve geliştiriciniz yoksa Gateway'e bakın. Özel bir ödeme akışınız, abonelik yenilemeleriniz veya çevrimdışı satışlarınız varsa doğrudan entegrasyon uzun vadede daha doğru sonuç verir.

Shopify, ikas ve Ticimax'ta CAPI nasıl açılır?

Shopify'da CAPI, Facebook & Instagram uygulamasındaki veri paylaşımı seviyesiyle açılır; ikas'ta ve çoğu yerli altyapıda ise Pixel kimliğinin yanına Meta'dan aldığınız erişim jetonunu girersiniz. Hepsinde iş, doğru ayarı seçip sonucu Test Events'te doğrulamaktır.

Shopify

Shopify yöneticisinde Satış kanalları > Facebook & Instagram > Ayarlar > Veri paylaşımı ayarları (Sales channels > Facebook & Instagram > Settings > Data sharing settings) yolunu izleyin ve Müşteri verisi paylaşımı bölümünde seviyeyi seçin. Shopify'ın yardım sayfasına göre Standart seviye yalnızca Meta Pixel kullanır; Gelişmiş (Enhanced) ve Maksimum (Maximum) seviyeler Conversions API'yi de açar ve eşleşme için müşterinin adını, konumunu, e-postasını ve telefonunu paylaşır. Shopify bu seçimi yaparken gizlilik politikanızı güncellemenizi de istiyor.

ikas

ikas'ın destek dokümanındaki akış şöyle: Meta'da Olay Yöneticisi > pikseliniz > Ayarlar > Dönüşümler API'si bölümünde, “Doğrudan entegrasyonu ayarlayın” altındaki “Dataset Quality API olmadan ayarlayın” seçeneğini işaretleyip Erişim Jetonu oluşturun. Ardından ikas panelinde Satış Kanalları > (kullandığınız satış kanalı) > Eklentiler alanına gidin, Facebook Conversion API satırındaki Bağla butonuyla jetonu yapıştırın, “Test Et” ile deneyip kaydedin. ikas aynı sayfada piksel ayarlarında “Otomatik İnternet Sitesi Eşleştirme”nin açık, “Olayları Otomatik Olarak Kodsuz Takip Edin” özelliğinin kapalı olmasını ve alan adınızın izin verilenler listesine eklenmesini öneriyor.

Ticimax ve diğer yerli altyapılar

Ticimax ve benzeri altyapılarda mantık aynıdır: Meta'da oluşturduğunuz erişim jetonu, Pixel kimliğiyle birlikte panelin entegrasyon ayarlarına girilir. Menü adları sürüme göre değişebildiği için alanı bulamazsanız altyapınızın destek ekibinden güncel yolu isteyin ve kurulumdan sonra aşağıdaki test adımını mutlaka yapın.

Pixel ile CAPI arasında tekilleştirme nasıl çalışır?

Meta, Pixel'deki eventID ile sunucudaki event_id aynıysa ve olay adları (event / event_name) eşleşiyorsa iki olayı tek sayar. Meta'nın dokümanına göre tekilleştirme, aynı event_id'li ilk olayın alınmasından sonraki 48 saat içinde gelen kopyalar için geçerlidir ve genelde önce gelen olay tercih edilir.

Uygulamada en sağlam yöntem, satın alma için sipariş numarasından türetilen bir kimlik kullanmaktır. Örneğin 10482 numaralı sipariş için tarayıcıda fbq('track', 'Purchase', {value: 1250, currency: 'TRY'}, {eventID: 'order_10482'}) gönderilir; sunucu tarafındaki olayda da "event_name": "Purchase" ve "event_id": "order_10482" yer alır. İki taraf aynı kaynaktan beslendiği için kimlikler asla ayrışmaz.

Neden bu kadar önemli olduğunu bir örnekle görelim (sayılar örnektir): bir haftada 120 gerçek sipariş var. Pixel bunların 95'ini, CAPI 118'ini yakaladı. Tekilleştirme çalışmazsa Olay Yöneticisi'nde 213'e varan Purchase görürsünüz; raporlanan satın alma sayısı ve ROAS gerçeğin yaklaşık 1,8 katı görünür ve algoritma yanlış sinyalle optimize eder. Tekilleştirme doğruysa sayı 120'ye yakın kalır.

Meta'nın ikinci bir yöntemi daha var: event_id yerine aynı olay adıyla birlikte fbp ve/veya external_id göndermek. Ancak doküman bu yöntemin yalnızca olay önce tarayıcıdan, sonra sunucudan geldiğinde çalıştığını, tek kaynak (yalnızca tarayıcı ya da yalnızca sunucu) kullanıldığında ise hiç işe yaramadığını belirtiyor. Bu yüzden event_id'yi birincil yöntem, fbp/external_id'yi yardımcı sinyal olarak görün.

Müşteri bilgileri nasıl normalize edilir ve hash'lenir?

E-posta, telefon, ad, soyad, şehir ve posta kodu gibi alanlar önce Meta'nın biçim kurallarına göre temizlenir, sonra SHA-256 ile hash'lenir; IP adresi, tarayıcı bilgisi, fbc ve fbp ise hash'lenmeden gönderilir. Hash'lemeden önceki temizlik yanlışsa hash de yanlış olur ve eşleşme gerçekleşmez.

Türkiye'de telefon formatı neden bu kadar sık bozuluyor?

Türk mağazalarında telefon genelde 0532 123 45 67, +90 (532) 123-45-67 veya 5321234567 olarak kaydedilir. Meta'nın kuralı, sembol ve baştaki sıfırların silinip ülke kodunun eklenmesidir; üçünün de hash öncesi hâli 905321234567 olmalıdır. Başında “+” veya “0” kalan, ya da “90” eklenmemiş numara farklı bir hash üretir ve o alan eşleşmeye hiç katkı vermez. Formu doldururken ülke kodunu ayrı alanda alıyorsanız birleştirirken tekrar eden “90” olup olmadığını da kontrol edin.

• Hash, normalize edilmiş değer üzerinden SHA-256 ile alınıyor
• Telefon ülke koduyla ve yalnızca rakamlardan oluşuyor
• E-posta küçük harfe çevrilmiş ve boşlukları temizlenmiş
• client_ip_address ve client_user_agent ham hâliyle gidiyor
• fbc ve fbp çerezleri sunucu olayına da ekleniyor
• Giriş yapmış müşteriler için sabit bir external_id gönderiliyor

Olay Eşleşme Kalitesi (EMQ) nedir, nasıl yükseltilir?

Olay Eşleşme Kalitesi, gönderdiğiniz müşteri bilgilerinin olayları bir Meta hesabıyla ne kadar iyi eşleştirdiğini 10 üzerinden puanlar. Puanı Olay Yöneticisi'nde veri setinizi açıp olay bazında görebilirsiniz; aynı veriyi Meta'nın Dataset Quality API'si de composite_score ve hangi eşleşme anahtarının olayların yüzde kaçında bulunduğunu gösteren match_key_feedback alanlarıyla verir.

EMQ'yu yükseltmenin yolu genelde yeni araç değil, eksik alanları tamamlamaktır. Satın alma olayında e-posta ve telefon neredeyse her zaman sizdedir; bunlar gitmiyorsa ilk düzeltilecek şey budur. Ardından fbc (reklam tıklama kimliği), fbp, IP ve user agent eklenir. Sayfa görüntüleme gibi üst huni olaylarında kişisel bilgi olmadığı için puanın düşük kalması normaldir; asıl dikkat etmeniz gereken Purchase, InitiateCheckout ve Lead olaylarıdır.

1. Ölç Olay Yöneticisi'nde Purchase olayının EMQ puanını ve eksik parametre önerilerini not edin.
2. Eksikleri bul Hangi anahtarın düşük oranda geldiğine bakın (çoğu zaman telefon veya fbc).
3. Düzelt Normalize kurallarını kodda veya platform ayarında düzeltin.
4. Doğrula Test Events'te yeni olayların parametrelerini kontrol edin.
5. Bekle ve karşılaştır Puanın güncellenmesi için birkaç gün verin, değişiklik tarihini kaydedin.

Dataset Quality API ayrıca tekilleştirme sağlığını da raporlar: event_coverage alanı, Pixel olaylarının son 7 günlük ortalamada yüzde kaçının CAPI ile de karşılandığını ve ortak tekilleştirme anahtarı taşıdığını gösterir. Bu oran düşükse sunucu tarafı bazı olayları hiç göndermiyor demektir.

Test Events ile kurulum nasıl doğrulanır?

Olay Yöneticisi'nde veri setinizi açıp Test Events sekmesine girin, verilen test kodunu sunucu olaylarında test_event_code olarak gönderin ve aynı olayın hem “Tarayıcı” hem “Sunucu” kaynaklı göründüğünü, birinin tekilleştirildiğini kontrol edin. Canlı bir test siparişi vermek en güvenilir denemedir.

1. Test kodunu al Test Events sekmesinde sunucu olaylarını test etme bölümündeki kodu kopyalayın.
2. Olayı tetikle Sitede ürün görüntüleyin, sepete ekleyin ve test siparişi verin.
3. Kaynakları kontrol et Purchase olayının tarayıcı ve sunucu satırlarını, event_id değerlerini karşılaştırın.
4. Parametreleri incele Sunucu olayında hash'lenmiş em/ph ile fbc, fbp, IP ve user agent'ın geldiğini görün.
5. Test kodunu kaldır Doğrulama bitince test_event_code'u canlı gönderimden çıkarın.

Kurulumdan sonra neleri izlemelisiniz?

İlk iki hafta Purchase sayısını mağaza siparişleriyle, EMQ puanını ve Olay Yöneticisi'ndeki uyarıları haftalık kontrol edin. CAPI'nin amacı rakamı büyütmek değil, gerçeğe yaklaştırmaktır; Meta'daki satın alma sayısı sipariş sayınızı belirgin şekilde aşıyorsa tekilleştirmeyi yeniden kontrol edin.

İzin tarafını da unutmayın. Sunucu olayları tarayıcı engellerinden etkilenmese de müşteriden hangi veriyi hangi amaçla paylaştığınızı gizlilik metninizde açıklamanız gerekir. Çerez onayı ve ölçüm ilişkisini Consent Mode v2 ve gizlilik yazımızda ayrıca ele aldık.

Meta, Google Ads ve GA4 dönüşümlerini tek ekranda karşılaştırmak, platformlar arasındaki sapmayı erken fark etmenin en pratik yoludur. Marpany'nin dönüşüm analizi ekranı bu kaynakları mağaza verisiyle yan yana koyar; böylece CAPI'yi açtıktan sonra satın almaların gerçekten sipariş sayısına yaklaşıp yaklaşmadığını görebilirsiniz. Hangi metriklere bakmanız gerektiğini reklam performansı KPI rehberinde, dönüşüm oranını artırmanın site tarafını da e-ticaret dönüşüm optimizasyonu makalesinde bulabilirsiniz.

Sıradaki adımlar

• Altyapınıza uygun yöntemi seçin: platform entegrasyonu, Gateway veya doğrudan API
• Temadaki veya GTM'deki mükerrer Pixel kodlarını temizleyin
• Purchase için sipariş numarasından türeyen ortak bir event_id kullanın
• Telefonları 90 ile başlayan, yalnızca rakamlardan oluşan formata çevirip hash'leyin
• Test Events'te test siparişiyle tarayıcı ve sunucu olaylarını doğrulayın
• Kurulumdan sonra EMQ ve uyarıları haftalık kontrol edin; yazıdaki menü adları Eylül 2026 itibarıyladır ve değişebilir