serkankaya.
English version
Birlikte çalışalım ↗

Meta Conversion API (CAPI) Nedir? Kurulum, EMQ ve Tekilleştirme

Meta Conversion API nedir, Pixel'den farkı ne, nasıl kurulur? Zorunlu parametreler, hashleme, Event Match Quality, tekilleştirme ve test adımları.

Meta Conversion API nedir sorusunun kısa cevabı şu: Meta Conversion API (Conversions API ya da kısaca CAPI), dönüşüm olaylarını tarayıcıdaki Pixel yerine reklamverenin sunucusundan, CRM’inden ya da uygulamasından doğrudan Meta’ya gönderen bir bağlantıdır. Olaylar tarayıcıya bağlı olmadığı için çerez kısıtları ve reklam engelleyiciler yüzünden kaybolan sinyallerin bir kısmı geri döner. Meta, bu yapının Pixel’in yerine değil yanında kullanılmasını öneriyor.

Bu yazıda Conversions API’nin nasıl çalıştığını, Pixel’den farkını, kurulum yollarını, zorunlu parametreleri ve hashleme kurallarını anlatıyorum. Ardından Event Match Quality’yi, tekilleştirmeyi ve yayına almadan önce yaptığım kontrolleri paylaşıyorum.

Meta Conversions API nasıl çalışır?

Kısa cevap

Meta Conversions API nasıl çalışır?

Kullanıcı sitede bir işlem yaptığında, sitenin sunucusu bu olayı bir HTTP isteğiyle Meta’nın Graph API’sindeki pikselin events adresine gönderir. İstekte olay adı, olay zamanı, olayın kaynağı ve hashlenmiş müşteri bilgileri bulunur. Meta bu bilgilerle olayı bir Meta hesabına ve reklam tıklamasına eşleştirir, ardından optimizasyon ve raporlamada kullanır.

Meta’nın geliştirici dokümantasyonu Conversions API’yi, reklamverenin pazarlama verisi ile reklam hedeflemesini ve ölçümü optimize eden Meta sistemleri arasında bağlantı kuran bir araç olarak tanımlıyor.[1] Pratikte bu bağlantı, sunucunun Meta’ya JSON biçiminde olay göndermesi demektir.

Site ya da CRM Sunucu Conversions API Meta Ads
Olay tarayıcıya uğramadan sunucudan Meta'ya gider; Pixel ise aynı olayı tarayıcıdan paralel olarak gönderir.

İstek, pikselin kimliğiyle oluşturulan /{PIXEL_ID}/events adresine POST olarak gider ve Olay Yöneticisi’nden (Events Manager) üretilen bir erişim belirteciyle (access token) yetkilendirilir. Meta’nın kullanım rehberine göre tek istekte en fazla 1.000 olay gönderilebilir.[6]

Sunucu tarafında olay iki yoldan oluşur. İlkinde tarayıcıdaki olay önce sitenin kendi ölçüm sunucusuna, örneğin bir server-side GTM kapsayıcısına gelir ve oradan Meta’ya iletilir. İkincisinde olay hiç tarayıcıdan geçmez. Ödeme onaylandığında ya da CRM’de bir lead “satış” aşamasına geçtiğinde, arka uç Meta’ya doğrudan istek gönderir.

Meta Pixel ile Conversions API arasındaki fark nedir?

Meta Pixel, kullanıcının tarayıcısında çalışan ve olayları oradan Meta’ya gönderen bir JavaScript kodudur; Conversions API ise olayları reklamverenin sunucusundan gönderir. Pixel sayfa görüntüleme ve kaydırma gibi tarayıcı davranışlarını kolayca yakalar. Conversions API ise ödeme onayı, iptal ya da CRM’de kapanan satış gibi tarayıcının görmediği sonuçları iletebilir.

Meta Pixel

  • Kullanıcının tarayıcısında çalışır
  • Kurulumu tek bir kod parçasıyla yapılır
  • Reklam engelleyiciler ve çerez kısıtları doğrudan etkiler
  • _fbp ve _fbc çerezlerini oluşturur
  • Yalnızca sitede olan olayları görür

Conversions API

  • Reklamverenin sunucusunda ya da CRM entegrasyonunda çalışır
  • Erişim belirteci ve sunucu tarafı kurulum ister
  • Tarayıcı kısıtlarından doğrudan etkilenmez
  • Çerez değerlerini sunucuya taşınırsa kullanabilir
  • Çevrimdışı ve CRM olaylarını da gönderebilir
İki yöntem birbirinin rakibi değil; Meta, Conversions API'nin Pixel ile birlikte kurulmasını öneriyor.

Meta bu birlikte kullanıma “redundant setup”, yani yedekli kurulum diyor ve reklamverenlerin Conversions API’yi Pixel’in yanında uygulamasını öneriyor.[2] Yedekli kurulumda tarayıcı olayı kaybolsa bile sunucu olayı Meta’ya ulaşır. İkisi de ulaştığında Meta tekilleştirme kurallarıyla tek olay sayar.

Bu farkın arkasındaki tarayıcı kısıtlarını ve sunucu taraflı ölçümün genel mantığını server-side tracking yazısında ayrıntılı anlattım. Burada Meta’ya özgü kurulum ve parametrelere odaklanıyorum.

Conversions API nasıl kurulur?

Conversions API’yi kurmanın dört yaygın yolu vardır: Olay Yöneticisi’ndeki kodsuz kurulum, e-ticaret ya da CRM altyapısının hazır Meta entegrasyonu, server-side GTM gibi bir etiket sunucusu ve doğrudan API entegrasyonu. Meta, Pixel’i kurulu olan reklamverenlerin Conversions API’yi Olay Yöneticisi’nden kod yazmadan kurabileceğini belirtiyor.[1]

YöntemKime uygunSınırı
Olay Yöneticisi kodsuz kurulumPixel’i olan, hızlı başlamak isteyen siteÖzel olay ve CRM verisi için sınırlı
Altyapı entegrasyonu (Shopify, WooCommerce, CRM)Hazır platform kullanan e-ticaret ve satış ekipleriGönderilen alanlar entegrasyona bağlı
Server-side GTMBirden çok platforma sunucudan veri gönderen ekiplerBarındırma ve bakım gerektirir
Doğrudan APIÖzel yazılımı ve kendi arka ucu olan işletmelerGeliştirme ve izleme sorumluluğu sende

Hangi yolu seçersen seç, kurulum sırası hemen hemen aynı kalır:

  1. Olay haritasını çıkar

    Hangi eylemin hangi olay adıyla gideceğini yaz: Lead, Schedule, Purchase gibi standart olaylar mı, yoksa özel olay mı? Değer, para birimi ve sipariş numarası alanlarını burada netleştir.

  2. Erişim belirtecini oluştur

    Olay Yöneticisi'nde pikselin ayarlarından Conversions API için erişim belirteci üret. Belirteci yalnızca sunucuda sakla; tarayıcı koduna ya da repoya yazma.

  3. Ortak event_id üret

    Pixel ve sunucu aynı olayı gönderecekse sipariş ya da başvuru numarası gibi benzersiz bir kimliği iki tarafa da aynı değerle ver.

  4. Müşteri bilgilerini hazırla

    İzin verilen alanları normalleştir, iletişim bilgilerini SHA-256 ile hashle. IP, tarayıcı bilgisi, fbc ve fbp değerlerini hashlemeden ekle.

  5. Test Events ile doğrula

    Olay Yöneticisi'ndeki Test Events ekranından aldığın test kodunu isteğe ekle, olayların doğru adla ve tekilleştirilmiş olarak geldiğini gör, sonra kodu kaldır.

Örnek istek

Aşağıdaki gövde, web sitesinde gerçekleşen bir satın almanın sunucudan gönderilmesini gösteriyor. Değerler örnektir; em ve ph alanları hashlenmiş olarak gider.

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1763550000,
      "event_id": "order-10482",
      "action_source": "website",
      "event_source_url": "https://www.ornek.com/odeme/tamamlandi/",
      "user_data": {
        "em": ["<sha256(küçük harfli e-posta)>"],
        "ph": ["<sha256(ülke kodlu telefon)>"],
        "client_ip_address": "203.0.113.10",
        "client_user_agent": "Mozilla/5.0 ...",
        "fbc": "fb.1.1763549000000.AbCdEf...",
        "fbp": "fb.1.1763540000000.1234567890"
      },
      "custom_data": { "currency": "TRY", "value": 1250 }
    }
  ]
}

Conversions API için hangi parametreler zorunlu?

Meta’nın sunucu olayı parametreleri belgesine göre her olayda event_name, event_time, user_data ve action_source zorunludur.[4] Web sitesinden gelen olaylarda event_source_url da gönderilmelidir. Bu dört alan eksikse olay işlenmez; eksik ya da tutarsız user_data ise olayın bir kişiyle eşleşme şansını düşürür.

  • event_name: Olayın adı. Standart olay adlarını (Purchase, Lead, Schedule) kullanmak raporlamayı ve optimizasyonu kolaylaştırır.
  • event_time: Olayın gerçekleştiği an, GMT’ye göre saniye cinsinden Unix zaman damgası. Meta’ya göre bu değer gönderim anından en fazla 7 gün önce olabilir. Daha eski bir olay varsa istek tümüyle hata döner ve içindeki hiçbir olay işlenmez.[4]
  • action_source: Dönüşümün nerede olduğu. Web sitesi için website, mağaza ya da klinikte tamamlanan satış için physical_store, sohbet için chat gibi değerler alır.
  • user_data: Olayı bir kişiyle eşleştirmeye yarayan müşteri bilgileri.

Çevrimdışı satışlarda kural farklıdır. Meta, physical_store kaynağıyla gönderilen mağaza içi ve çevrimdışı işlemlerin dönüşümden sonraki 62 gün içinde yüklenmesini öneriyor.[6] Sağlık turizminde operasyon günü ya da e-ticarette kapıda ödemeli teslimat çoğu zaman bu senaryoya girer.

Hashleme ve normalleştirme

Meta’nın müşteri bilgisi parametreleri belgesine göre e-posta, telefon, ad, soyad, doğum tarihi, cinsiyet, şehir, eyalet, posta kodu ve ülke alanları SHA-256 ile hashlenmelidir.[3] client_ip_address, client_user_agent, fbc ve fbp ise hashlenmeden gönderilir. external_id için hashleme önerilir ama zorunlu değildir.

Hashlemeden önce değer normalleştirilir. E-postada baştaki ve sondaki boşluklar silinir, tüm harfler küçültülür. Telefonda semboller, harfler ve baştaki sıfırlar kaldırılır; ülke kodu her zaman eklenir.[3] Türkiye’deki bir numara için bu, 0532 … yerine 90532… biçimi demektir.

Çerez onayı tarafında, kullanıcının reklam çerezlerini reddettiği durumda sunucu etiketlerinin de bu tercihe uyması gerekir. Onay sinyalinin tarayıcıdan sunucuya nasıl taşındığını Consent Mode v2 yazısında anlattım.

Event Match Quality nedir, nasıl artırılır?

Event Match Quality (olay eşleşme kalitesi), Meta’nın sunucudan gelen bir olayı Meta hesabı olan bir kişiyle ne kadar iyi eşleştirebildiğini gösteren puandır. Olay Yöneticisi’nde olay bazında görünür. Puanı belirleyen şey, olayla birlikte gönderilen müşteri bilgisi alanlarının kapsamı ve doğruluğudur.

Eşleşmeyi en çok güçlendiren alanlar şunlardır:

  1. fbc: Kullanıcı Meta reklamına tıkladığında açılış sayfası URL’sine fbclid parametresi eklenir. Pixel bu değeri _fbc çerezine yazar. Meta’nın belgesine göre fbc değeri fb.1.<oluşturma zamanı>.<fbclid> biçimindedir ve fbclid büyük-küçük harfe duyarlıdır.[5]
  2. fbp: Pixel, tarayıcıda yoksa _fbp çerezine benzersiz bir tarayıcı kimliği kaydeder.[5] Bu değeri sunucuya taşımak, sunucu olayını aynı tarayıcıdaki Pixel olayına bağlar.
  3. E-posta ve telefon: Form ya da ödeme adımında alınan, doğru normalleştirilmiş ve hashlenmiş iletişim bilgileri.
  4. IP adresi ve tarayıcı bilgisi: Web sitesi olaylarında isteğin geldiği IP ve user agent.
  5. external_id: Sitedeki ya da CRM’deki müşteri numarası. Aynı kişiye ait olayları birbirine bağlar.

En sık gördüğüm hata, sunucu olayında fbc ve fbp alanlarının boş gitmesidir. Kullanıcı reklamdan geldiği hâlde tıklama kimliği sunucuya taşınmadıysa, Meta olayı o tıklamaya bağlayamaz. Çözüm, açılış sayfasında bu çerezleri okumak ve form ya da sipariş kaydıyla birlikte sunucuya iletmektir.

Pixel ve Conversions API olayları çift sayılırsa ne yapılmalı?

Pixel ve Conversions API aynı olayı gönderiyorsa, iki olayda da aynı event_name ve aynı event_id bulunmalıdır. Meta’nın tekilleştirme belgesine göre Pixel’deki eventID değeri, sunucudaki event_id ile birebir eşleşmelidir.[2] Eşleşme yoksa aynı satın alma iki kez sayılır ve ROAS olduğundan yüksek görünür.

Tekilleştirmenin bir zaman sınırı da var. Meta, belirli bir event_id ile ilk olayı aldıktan sonraki 48 saat içinde gelen kopyaları tekilleştiriyor.[2] Bu yüzden sunucu olayını günler sonra gönderen bir kurulumda kimlik eşleşse bile çift sayım riski doğar.

Meta, alternatif olarak olay adı ile fbp ya da external_id üzerinden tekilleştirmeyi de destekliyor. Ancak bu yöntem yalnızca önce tarayıcı, sonra sunucu olayı geldiğinde çalışıyor.[2] Ben her olayda event_id göndermeyi tercih ediyorum; kurulumu da hata ayıklamayı da sadeleştiriyor.

Conversions API sağlık turizmi ve e-ticarette nasıl kullanılır?

Conversions API’nin en büyük değeri, gerçek sonucun sitede değil satış sürecinde oluştuğu işlerde ortaya çıkar. Sağlık turizminde süreç lead → konsültasyon → operasyon şeklinde ilerler. E-ticarette ise satın alma değeri iade, iptal ya da kapıda ödeme yüzünden sonradan değişebilir.

Sağlık turizmi: Sitedeki form ya da WhatsApp tıklaması bir başlangıçtır. Optimizasyon için asıl değerli olay, hasta koordinatörünün lead’i nitelikli bulması, depozitonun alınması ya da operasyonun gerçekleşmesidir. Bu aşamaları CRM’den Conversions API ile göndermek, Meta’nın kaliteli lead getiren kitleyi öğrenmesini sağlar. Meta’nın kendi lead formlarından gelen kayıtlarda lead_id alanı hashlenmeden gönderilir.[3] Bu akışın Google tarafını sağlık turizminde offline dönüşüm yazısında, WhatsApp kanalını ise WhatsApp dönüşüm takibi yazısında anlattım. Sektöre özel yaklaşımı sağlık turizmi pazarlaması sayfasında özetliyorum.

E-ticaret: Satın alma olayını ödeme sağlayıcısının onayından sonra sunucudan göndermek, tarayıcının teşekkür sayfasına hiç ulaşmadığı siparişleri de ölçüme katar. Sepet içeriği, para birimi ve kesinleşen değer sipariş sisteminden geldiği için daha güvenilirdir. Kâr odaklı teklif stratejisi kuruyorsan bu değeri POAS mantığıyla zenginleştirmek de mümkündür.

Kurulum doğru çalışıyor mu, nasıl kontrol edilir?

Conversions API kurulumunu doğrulamak için olayların Meta’ya ulaştığını, zorunlu alanların dolu olduğunu, tekilleştirmenin çalıştığını ve eşleşme kalitesinin yeterli olduğunu ayrı ayrı kontrol etmek gerekir. Meta, test için Olay Yöneticisi’ndeki Test Events ekranında üretilen kodun test_event_code parametresiyle gönderilmesini istiyor.[6] Bu kod yalnızca test içindir ve canlı gönderimde kaldırılmalıdır.

Meta Conversions API yayın öncesi kontrol listesi0/10

Son madde en çok atlanan kontrol. Olay Yöneticisi’nde her şey yeşil görünse bile Meta’daki dönüşüm sayısını CRM ya da sipariş sistemiyle düzenli karşılaştırmak, hem eksik hem çift sayımı erken fark etmeni sağlar.

Nereden başlamalı?

Meta Conversions API, dönüşüm olaylarını sunucudan Meta’ya ileten ve Pixel’in kaçırdığı sinyallerin bir kısmını geri getiren bir bağlantıdır. Doğru çalışması için zorunlu parametrelerin dolu olması, müşteri bilgilerinin normalleştirilip hashlenmesi ve Pixel ile aynı event_id’nin kullanılması gerekir. Kurulumun gerçek değeri ise CRM’deki satış ve randevu gibi sonuçları Meta’ya geri bildirdiğinde ortaya çıkar.

Benim önerim önce olay haritasını ve onay yapısını netleştirmek, sonra en basit kurulum yoluyla başlayıp Test Events ile doğrulamak. Ardından fbc, fbp ve iletişim bilgileriyle eşleşme kalitesini iyileştirmeye ve CRM olaylarını eklemeye geçmek gerekiyor. Ölçüm ve reklam yönetimini birlikte nasıl kurduğumu performans pazarlama sayfasında, yazılım tarafındaki entegrasyon işlerini yazılım geliştirme sayfasında anlatıyorum.

Bu yazıdaki terimler

action_source
action_source, Conversions API'ye gönderilen her olayda zorunlu olan ve dönüşümün nerede gerçekleştiğini belirten parametredir. Web sitesi için website, mağaza içi satış için physical_store, sohbet uygulaması için chat ya da sistem tarafından üretilen olaylar için system_generated gibi değerler alır.
Event Match Quality
Event Match Quality, Meta'nın sunucudan gelen bir olayı Meta hesabı olan bir kişiyle ne kadar iyi eşleştirebildiğini gösteren olay eşleşme kalitesi puanıdır. Puan, olayla birlikte gönderilen e-posta, telefon, IP, tarayıcı bilgisi ve çerez kimliği gibi müşteri bilgisi alanlarının kapsamına ve doğruluğuna bağlıdır.
fbclid
fbclid, Meta reklamına ya da Facebook ve Instagram'daki bir linke tıklayan kullanıcının açılış sayfası URL'sine eklenen tıklama kimliği parametresidir. Meta Pixel bu değeri _fbc çerezine yazar; Conversions API isteğinde fbc alanıyla gönderildiğinde dönüşüm reklam tıklamasına bağlanabilir.
Meta Conversions API
Meta Conversions API, reklamverenin sunucusu, CRM'i ya da uygulaması ile Meta'nın reklam sistemleri arasında doğrudan bağlantı kuran ve dönüşüm olaylarını sunucudan ileten bir arayüzdür. Kısaca CAPI, Türkçe arayüzde Dönüşümler API'si olarak geçer ve Meta Pixel ile birlikte kullanılması önerilir.
Tüm sözlük ↗

Sık sorulan sorular

Meta Conversion API nedir?

Meta Conversion API (Conversions API, CAPI), reklamverenin sunucusundan, CRM'inden ya da uygulamasından Meta'ya doğrudan dönüşüm olayı gönderen bir bağlantıdır. Olaylar tarayıcıya bağlı kalmadan iletildiği için Pixel'in kaçırdığı sinyallerin bir kısmı reklam optimizasyonuna geri döner.

Conversions API, Meta Pixel'in yerine geçer mi?

Hayır, Meta iki yöntemin birlikte kullanılmasını öneriyor. Pixel tarayıcıdaki davranışı ve çerez kimliklerini yakalar, Conversions API ise sunucudaki kesin sonucu iletir. İkisi aynı olayı gönderiyorsa olay adı ve event_id eşleşmeli, yoksa dönüşüm çift sayılır.

Conversions API kurmak için yazılımcı gerekir mi?

Her zaman değil. Pixel'i kurulu olan bir site, Olay Yöneticisi'ndeki kodsuz kurulum ya da e-ticaret altyapısının Meta entegrasyonuyla başlayabilir. CRM'den satış göndermek, özel olaylar tasarlamak ya da server-side GTM kullanmak ise teknik bilgi ister.

Conversions API ile hangi müşteri verileri gönderilir?

E-posta, telefon, ad, soyad, şehir, posta kodu ve ülke gibi iletişim bilgileri SHA-256 ile hashlenerek gönderilir. IP adresi, tarayıcı bilgisi ile fbc ve fbp çerez değerleri hashlenmeden iletilir. Hangi alanın gönderileceği, kullanıcıdan alınan izne ve KVKK yükümlülüklerine göre belirlenmelidir.

Conversions API olayları ne kadar geriye dönük gönderilebilir?

Web sitesi olaylarında event_time, gönderim anından en fazla 7 gün önce olabilir. Daha eski bir olay içeren istek tamamen reddedilir. Mağaza içi ve çevrimdışı satışlarda ise Meta, işlemlerin dönüşümden sonraki 62 gün içinde yüklenmesini öneriyor.

Kaynaklar

  1. Meta for Developers: Conversions API
  2. Meta for Developers: Handling Duplicate Pixel and Conversions API Events
  3. Meta for Developers: Customer Information Parameters
  4. Meta for Developers: Server Event Parameters
  5. Meta for Developers: ClickID and the fbp and fbc Parameters
  6. Meta for Developers: Using the Conversions API