Meta Pikseli ve Dönüşümler API'si: Kurulum, Olaylar ve Kontrol

Meta pikseli (Meta Pixel), mağazanızdaki ürün görüntüleme, sepete ekleme ve satın alma gibi eylemleri ziyaretçinin tarayıcısından Meta'ya gönderir; Dönüşümler API'si (Conversions API) aynı olayları sunucunuzdan ya da mağaza altyapınızdan gönderir. Meta, ikisinin birlikte kurulmasını ve aynı olayların iki kanaldan paylaşılmasını önerir. Kurulum altı adımda ilerler: piksel kurulur, e-ticaret olayları parametreleriyle kontrol edilir, Dönüşümler API'si bağlanır, iki kanalda olay kimliği eşlenir, olaylar Test Events ekranında sınanır ve Olay Yöneticisi'nde izlenir.

Adım	Ne Yapılır
1. Piksel	Piksel kimliği altyapı paneline girilir ya da taban kod her sayfanın <head> bölümüne eklenir; PageView olayı görülür.
2. E-Ticaret Olayları	ViewContent, AddToCart, InitiateCheckout, AddPaymentInfo ve Purchase parametreleriyle kontrol edilir.
3. Dönüşümler API'si	Altyapı entegrasyonu, Olay Yöneticisi, Conversions API Gateway, sunucu tarafı Google Etiket Yöneticisi ya da doğrudan entegrasyonla bağlanır.
4. Olay Kimliği	Aynı olay iki kanalda aynı adı ve aynı olay kimliğini (eventID, event_id) taşır.
5. Test	Tarayıcı olayları Test Events ekranında, sunucu olayları test_event_code ile sınanır.
6. İzleme	Bağlantı yöntemi, tekilleştirme, olay tazeliği ve Event Match Quality puanı izlenir.

Pikselin ve Dönüşümler API'sinin tanımı sözlükteki Meta Pixel ve Conversions API maddelerindedir; bu yazı kurulum ve kontrol sırasını anlatır. Meta menü adlarını zaman zaman değiştirdiği için ekran adlarının yanında İngilizce arayüzdeki karşılığı da verilir.

Meta'nın önerdiği yedekli kurulum

Piksel, ziyaretçinin tarayıcısında çalışan bir JavaScript parçasıdır; gönderdiği olaylar dönüşüm ölçümünde, kitle oluşturmada ve Advantage+ katalog reklamlarında kullanılır. Dönüşümler API'si ise sunucuyu, web sitesi altyapısını ya da CRM'i Meta'ya bağlar; web olaylarının yanında işletme mesajlaşması ve çevrim dışı olayları da taşır ve Meta sunucu olaylarını piksel olayları gibi işler.

Meta'nın önerisi yedekli kurulumdur (redundant setup): pikselle gönderilen olayların aynısı sunucudan da gönderilir. Böylece ağ bağlantısı ya da sayfa yükleme hatası yüzünden pikselden ulaşmayan bir web olayı sunucudan ulaşabilir. Meta iki düzen daha tanımlar:

• Bölünmüş Kurulum: farklı olaylar farklı kanaldan gider; Meta'nın örneğinde PageView ve ViewContent pikselden, Lead ve Purchase sunucudan gönderilir. Meta bu düzeni yedekli kurulumdan daha az uygun bulur.
• Yalnız Sunucu: bütün olaylar Dönüşümler API'sinden gider; Meta bu düzene geçmeden önce yedekli ya da bölünmüş kurulumun yapılmasını ister.

Sitenizde piksel zaten çalışıyorsa Dönüşümler API'si onun uzantısı olarak kurulur ve iki kanalın olayları aynı piksel kimliğine gönderilir. Altyapınızın belgesi temel ölçüm için pikselin yeterli olduğunu yazıyorsa bu doğrudur, ölçüm pikselle de çalışır; Meta'nın önerisi ise ikisinin birlikte kullanılmasıdır.

Meta pikselinin kurulumu ve ilk kontrol

Piksel, Olay Yöneticisi'nde (Events Manager) veri bağlama adımında kaynak olarak Web seçilip ad verilerek oluşturulur. Meta arayüzü pikseli bazı hesaplarda veri seti (dataset) adıyla gösterir; veri seti kimliği ile piksel kimliği aynı olabilir.

Hazır bir mağaza altyapısında piksel genellikle panelden bağlanır: yalnızca rakamlardan oluşan piksel kimliği panele girilir ve olayları altyapı gönderir. Meta'nın gösterdiği uzun kodu ayrıca temaya ya da takip kodu alanına eklemek aynı olayların iki kez gelmesine yol açar; bunun bir örneği ideasoft Meta pikselinde eski kodlar ve çift olaylar maddesindedir.

Kendi yazılımınız varsa Meta, taban kodun izlenen her sayfanın <head> bölümüne eklenmesini önerir; bu yerleşim kodun engellenme ihtimalini azaltır ve daha erken çalışmasını sağlar. Mobil siteniz ayrı bir adresteyse kod ona da eklenir.

Pikselin bağlı olduğu veri seti doğru işletme portföyünde olmalı ve kullanılacak reklam hesabına bağlanmalıdır. Alan adı da İşletme Ayarları'nda Marka Güvenliği altındaki Alan Adları bölümünden, meta etiketi ya da DNS TXT kaydıyla doğrulanır.

Kurulumdan sonra pikselli bir sayfa açılır; Olay Yöneticisi'nde pikselin ayrıntısında yeni bir PageView olayı görünüyorsa piksel çalışıyordur. Olay görünmüyorsa birkaç dakika beklenip sayfa yenilenir.

Sayfa düzeyindeki kontrol, Meta'nın Chrome ve Microsoft Edge eklentisi Meta Ads Data Advisor (önceki adıyla Meta Pixel Helper) ile yapılır. Reklam engelleyici kapatılır, eklenti simgesine tıklanır ve izlenecek eylem, örneğin sepete ekleme yapılır. Eklenti pikseli Active (doğru çalışıyor), Warning (doğru kurulmamış) ya da Inactive (olay göndermiyor) diye gösterir; piksel aktif görünmüyorsa ilk bakılacak yer burasıdır. Piksel etkin olsa da tek tek olaylar uyarı taşıyabilir.

Meta, Data Advisor ile kurulan yeni piksellerde standart olayları kendiliğinden algılama seçeneğini işaretli getirir; ayar Olay Yöneticisi'nde Settings altındaki "Track events automatically without code" ile kapatılır. Olayları mağaza altyapınız gönderiyorsa bu ayar için altyapının Meta entegrasyonu belgesindeki yönergeyi izleyin.

E-ticaret olayları ve gönderilecek parametreler

Bir e-ticaret sitesinde izlenen standart olaylar, Meta'nın tanımına göre şu anlarda ve şu parametrelerle gönderilir:

Olay	Ne Zaman Gönderilir	Parametreler
PageView	Her sayfa yüklemesinde	Taban kod kendiliğinden gönderir; Meta bu çağrının olduğu gibi bırakılmasını ister.
ViewContent	Ürün sayfası ziyaret edildiğinde	content_ids, content_type, contents, currency, value; katalog reklamı için contents ya da content_ids gerekir.
AddToCart	Ürün sepete eklendiğinde	content_ids, content_type, contents, currency, value; katalog reklamı için contents gerekir.
InitiateCheckout	Ödeme adımına girildiğinde	content_ids, contents, currency, num_items, value
AddPaymentInfo	Ödeme sırasında ödeme bilgisi eklendiğinde	content_ids, contents, currency, value
Purchase	Satın alma tamamlandığında; teşekkür ya da onay sayfasında	currency ve value zorunlu; ayrıca content_ids, content_type, contents, num_items. Katalog reklamı için contents ya da content_ids gerekir.

Purchase olayında currency ve value zorunludur; value, değer optimizasyonu kullanan olaylarda da zorunludur. value para tutarını gösteren bir sayı, currency üç harfli ISO 4217 kodudur (Türk lirası için TRY). Tutarın sipariş toplamıyla eşlenmesi ve yerel fiyat yazımının sayıya çevrilmesi Meta Purchase olayında değer ve para birimi hataları maddesinde anlatılır.

content_type, gönderilen kimlik bir ürünse product, renk ya da beden gibi varyantları birleştiren bir ürün grubuysa product_group olur; tür verilmezse Meta olayı aynı kimliği taşıyan her öğeyle eşleştirir. contents her ürün için id ve quantity alanlarını taşır, item_price isteğe bağlıdır; content_ids ise SKU gibi ürün kimliklerinin listesidir. Olaydaki ürün kimliğinin katalogdaki kimlikle aynı olması gerekir; ayrıntısı Meta katalog ve olay verisinde ürün kimliği uyuşmazlığı maddesindedir.

Dönüşümler API'sinin kurulum yolları

Dönüşümler API'si için piksel kimliği, Meta Business Suite'teki işletme hesabı ve erişim jetonu (access token) gerekir. Yol, mağazanın altyapısına ve geliştirici kaynağınıza göre seçilir:

• Altyapının Meta Entegrasyonu: mağaza altyapınızın hazır bağlantısıdır; piksel kimliği ve erişim jetonu panele girilir, kurulumda altyapının kendi yönergesi izlenir.
• Olay Yöneticisi'nden Kurulum: sitede piksel varsa ve yalnızca web olayları gönderilecekse Meta, Dönüşümler API'sinin barındırma ya da bakım gerektirmeden Olay Yöneticisi'nden açılabildiğini belirtir.
• Conversions API Gateway: Olay Yöneticisi'nden yapılandırılır, ama sunucu örneği işletmenin kendi bulut hesabında (AWS ya da Google Cloud) çalışır; tekilleştirme için olay kimliğini kendisi üretir ve iki kanala taşır.
• Sunucu Tarafı Google Etiket Yöneticisi: GA4 web etiketinin verisi bulutta kurulan bir sunucu kapsayıcısına gider, oradan Meta'nın Conversions API etiketiyle Meta'ya iletilir. Bu yönteme sunucu tarafı etiketleme denir.
• Doğrudan Entegrasyon: sitenizin sunucusu olayları Meta'nın Graph API uç noktasına gönderir; Meta bunun için Business SDK'yı (Python, Java, Ruby, PHP, Node) önerir. Bu yol geliştirici işidir.
• Meta Ads Data Advisor ile Kurulum: eklenti, Google Etiket Yöneticisi ve desteklenen bazı mağaza altyapıları üzerinden pikseli ve Dönüşümler API'sini kendiliğinden kurabilir.

Erişim jetonu, Olay Yöneticisi'nde pikselin Ayarlar (Settings) sekmesindeki Dönüşümler API'si bölümünden üretilir; İngilizce arayüzde "Set up manually" altındaki "Generate access token" bağlantısı kullanılır. Bağlantı yalnızca işletmede geliştirici yetkisi olan kullanıcılara görünür ve uygulama incelemesi (App Review) gerekmez. Jeton, sunucunuzun Meta'ya olay göndermesini sağlayan gizli bir anahtardır; ekran görüntüsünde, e-postada ya da destek talebinde paylaşılmaz.

Sunucu olayında gönderilen alanlar

Hazır entegrasyonda bu alanları altyapı doldurur; doğrudan entegrasyonda ve sorun ararken Meta'nın parametre belgesindeki alanları bilmek gerekir. Bir web olayının başlıca alanları şunlardır:

• Zorunlu Alanlar: event_name, event_time, user_data ve action_source; web olaylarında ayrıca event_source_url ve client_user_agent. Meta, event_id ve external_id alanlarının da her olayla gönderilmesini önerir.
• event_time: olayın GMT'ye göre Unix saniyesi cinsinden zamanıdır ve gönderimden en çok yedi gün öncesine ait olabilir. Yedi günden eski tek bir olay, istekteki bütün olayların hatayla geri dönmesine yol açar.
• action_source: olayın nerede gerçekleştiğini söyler; web mağazasında website değeri kullanılır. Meta, değerin doğru olmasını reklamverenin sorumluluğu sayar.
• event_source_url: olayın gerçekleştiği sayfanın adresidir ve doğrulanmış alan adınızla eşleşmelidir.
• user_data: en az bir doğru biçimli müşteri bilgisi taşır. client_ip_address ve client_user_agent sunucu olayına tarayıcıdan kendiliğinden gelmez, elle eklenir.

E-posta, telefon, ad ve soyad gibi müşteri bilgileri gönderilmeden önce normalleştirilir ve SHA-256 ile karmalanır; IP adresi, tarayıcı bilgisi, fbp ve fbc karmalanmaz. Telefonun ülke koduyla yazılması, iki kez karmalama ve benzeri biçim konuları Meta Conversions API kullanıcı verisinde biçim ve eşleştirme maddesindedir.

Olaylar gerçekleştiği anda, en geç bir saat içinde gönderilir. Meta'ya göre iki saatten sonra gönderilen olaylarda reklam performansı belirgin biçimde düşebilir; 24 saat ve üzeri gecikmede ilişkilendirme ve teslim optimizasyonunda belirgin sorun yaşanabilir. Bir istekte en çok 1.000 olay gönderilir.

Tarayıcı ve sunucu olayında aynı olay kimliği

Aynı olay iki kanaldan gidiyorsa tarayıcı olayına verilen eventID ile sunucu olayındaki event_id aynı değeri, iki olay da aynı adı taşır; sipariş numarası bu kimlik için kullanılabilir, Conversions API Gateway ise kimliği kendisi üretir. Eşleşmenin kuralları ve sık görülen kimlik uyuşmazlıkları Meta Pixel ve Conversions API olayları neden tekilleştirilir maddesinde, kavramın kendisi sözlükteki olay tekilleştirme maddesinde anlatılır.

Test Events ile kurulumu sınama

Tarayıcı olayları Olay Yöneticisi'ndeki Olayları Test Et (Test Events) sekmesinde sınanır: İnternet sitesi seçilir, mağazanın adresi https:// ile tam olarak yazılır ve açılan sitede ürün görüntüleme, sepete ekleme ve ödeme başlatma yapılır. Türkçe arayüzde olaylar Türkçe adlarıyla (örneğin "sepete ekleme işlendi"), Meta Ads Data Advisor'da İngilizce adlarıyla (AddToCart) görünür.

Sunucu olayları için aynı sekme bir test kimliği üretir; kimlik istekte test_event_code olarak gönderildiğinde olaylar test penceresinde görünür. Meta, test olaylarında kendi ad, e-posta ve telefon bilginizin kullanılmasını önerir, çünkü bir Meta hesabıyla eşleşmeyen test olayları atılabilir.

Test kodunu canlı gönderimde bırakmayın: Meta'ya göre test_event_code taşıyan olaylar atılmaz, Olay Yöneticisi'ne akar ve hedefleme ile reklam ölçümünde kullanılır. API yanıtının okunması ve canlıya geçişte bakılacaklar Meta Conversions API test olayları maddesindedir.

Gönderilen olaylar yaklaşık 20 dakika içinde Olay Yöneticisi'nde görünür; düğme tıklaması gibi Data Advisor'ın güvenilir göstermediği olaylar da Test Events ekranında doğrulanır.

Yayına almadan önce kontrol listesi

Olay Yöneticisi'nde pikselin Overview sayfası olayları tekilleştirmeden ve izin denetimlerinden önceki sayılarıyla gösterir; iki kanal birlikte çalışırken toplamın iki kat görünmesi bu yüzden tek başına hata değildir, tekilleştirme sonucu ayrıca okunur. Yayına almadan önce şunlar kontrol edilir:

• PageView: her sayfada bir kez geliyor; Data Advisor'da yinelenen piksel kodu uyarısı yok.
• Satın Alma Değeri: Purchase olayında value ve currency dolu; tutar sipariş toplamıyla aynı.
• Bağlantı Yöntemi: Overview'da "Connection Method" altında hem tarayıcı hem sunucu kanalı görünüyor.
• Tekilleştirme: olay ayrıntısındaki "Event Deduplication" sekmesinde oran yüksek, uyarı yok.
• Tazelik: "Event Freshness" sekmesinde ortalama gecikme gerçek zamana yakın.
• Event Match Quality: puanın ayrıntısındaki öneriler okundu; Meta genellikle 6,0 ve üzerini hedeflemeyi önerir.
• Test Kodu: test_event_code canlı gönderimde yok.
• İzin: çerez iznini reddeden ziyaretçide ne piksel ne sunucu olayı gidiyor.
• Alan Adı: alan adı doğrulandı ve sunucu olaylarındaki event_source_url bu alan adıyla eşleşiyor.

Sık hatalar ve teşhis sırası

Sorun ararken önce olayın gelip gelmediğine, sonra kaç kez geldiğine, en son taşıdığı bilgiye bakılır; her belirtinin ayrıntısı bağlantıdaki maddededir:

1. Piksel Inactive Görünüyor: reklam engelleyici kapalıyken Data Advisor'a ve taban kodun her sayfanın <head> bölümünde olduğuna bakılır; pikselin çalıştığının nasıl anlaşılacağı sözlükteki Meta Pixel maddesindedir.
2. Test Olayı Görünmüyor: test_event_code değeri, yedi günden eski olmayan event_time ve test olayında kendi müşteri bilginizin kullanılması kontrol edilir; ayrıntı Meta Conversions API test olayları maddesinde.
3. Aynı Olay İki Kez Geliyor: piksel kodunun panelde, temada ya da etiket yöneticisinde ikinci kez tanımlı olup olmadığına bakılır; altyapıya özgü örnekler ideasoft Meta pikselinde eski kodlar ve Ticimax Meta Conversion API kurulumunda çift olay maddelerinde.
4. Tarayıcı ve Sunucu Olayı Ayrı Sayılıyor: olay ayrıntısındaki "Event Deduplication" sekmesinde tekilleştirme oranına ve anahtar kullanımına bakılır; ayrıntı olay tekilleştirme maddesinde.
5. Satın Alma Değeri Eksik ya da Yanlış: value ya da currency alanı eksik olan olay Meta'ya yine ulaşır ama değer optimizasyonunda kullanılamaz; Purchase olayındaki değerler sipariş toplamıyla karşılaştırılır, ayrıntı değer ve para birimi hataları maddesinde.
6. Event Match Quality Düşük: puanın ayrıntısındaki öneriler ve müşteri bilgisi alanlarının biçimi kontrol edilir; ayrıntı kullanıcı verisinde biçim ve eşleştirme maddesinde.
7. Katalog Ürünü Olayla Eşleşmiyor: olaydaki content_ids değeri katalogdaki ürün kimliğiyle karşılaştırılır; ayrıntı ürün kimliği uyuşmazlığı ve ikas Meta kataloğu ve piksel bağlantısı maddelerinde.
8. Shopify Özel Pikseli Meta'ya Ulaşmıyor: bağlantı, müşteri izni ve hedef istek ayrı ayrı doğrulanır; ayrıntı Shopify özel piksel olayı maddesinde.

Ölçüm doğru çalıştığı hâlde satış gelmiyorsa yayın durumu, reklam incelemesi ve öğrenme aşaması kontrolleri Meta reklamı aktif ama satış gelmiyor yazısında anlatılır.

Çerez izni, KVKK ve verinin yurt dışına aktarımı

Meta pikseli, ziyaretçi çerez iznini verene kadar consent komutuyla duraklatılabilir; Meta bu komutun her sayfada ve pikselin başlatılmasından önce çalışmasını, onay gelince pikselin yeniden açılmasını ister. Meta'ya göre piksel verisinde uyguladığınız izin mantığı sunucu olaylarında da uygulanır; çerez iznini reddeden ziyaretçinin olayı sunucudan da gönderilmez.

Meta'nın İşletme Araçları Koşulları da piksel kullanan işletmeden, pikselin bulunduğu sayfalarda ziyaretçiyi verinin toplanması ve kullanılması hakkında açıkça bilgilendirmesini, onay gereken durumlarda Meta çerezlerinden önce onay almasını ve iletişim bilgilerini Meta'nın belirttiği biçimde şifreleyerek göndermesini ister.

Kişisel Verileri Koruma Kurumu'nun Çerez Uygulamaları Hakkında Rehberi'ne göre davranışsal reklamcılık için kullanılan çerezler açık rıza gerektirir. Açık rızanın ne olduğu sözlükteki açık rıza maddesinde, çerezlerin ne işe yaradığı çerez nedir yazısında anlatılır.

Meta'ya gönderilen verinin 6698 sayılı Kişisel Verilerin Korunması Kanunu'ndaki yurt dışına aktarım kuralları karşısındaki durumunu hukuk danışmanınızla değerlendirin. Bu yazı genel bilgilendirme içindir, hukuki görüş yerine geçmez.

Uzman desteği gerektiren durumlar

Altyapı entegrasyonuyla elle eklenmiş kodlar birlikte çalışıyorsa, Dönüşümler API'si sunucu tarafı etiketleme ya da doğrudan entegrasyonla kurulacaksa veya Olay Yöneticisi'ndeki sayılar sipariş kayıtlarıyla açıklanamıyorsa kurulum bütün olarak incelenir. AdPix, Meta reklam yönetimi kapsamında pikseli ve Dönüşümler API'sini mağazanın altyapısına göre kurar, her olayın doğru sayfada, doğru tutarla ve tek kez geldiğini denetler ve alan adı doğrulamasını yapar. Google tarafındaki ölçüm aynı izin düzeniyle GA4 e-ticaret ölçümü kurulumu hizmetinde ele alınır.

Meta pikseli ve Dönüşümler API'si için diğer rehberler

• Meta reklam yönetimi
• Meta reklamı aktif ama satış gelmiyor
• ROAS hesaplama aracı
• Conversions API nedir
• Etkinlik eşleşme kalitesi (Event Match Quality)
• WhatsApp Business ile sipariş almak

Meta pikseli ve Dönüşümler API'si hakkında sık sorulan sorular

Purchase olayında hangi parametreler zorunludur?

Meta'nın standart olaylar belgesine göre Purchase olayında currency ve value zorunludur; value sayı, currency üç harfli para birimi kodu olarak gönderilir. Advantage+ katalog reklamları kullanılıyorsa ürün kimliğini taşıyan contents ya da content_ids alanı da gerekir.

Meta Ads Data Advisor bir olayı neden göstermeyebilir?

Eklenti, sayfayı yenilemeyen ya da doğrudan piksel çağrısı yapmayan eylemleri, site kurulumuna göre bazı düğme tıklamalarını ve özel dönüşümleri algılamayabilir. Böyle bir olay Meta'ya gidiyor olabilir; emin olmak için Olay Yöneticisi'ndeki Test Events ekranına bakılır.

Erişim jetonu oluşturma bağlantısı neden görünmüyor?

Meta'ya göre pikselin Settings sekmesindeki 'Generate access token' bağlantısı yalnızca işletmede geliştirici yetkisi olan kullanıcılara görünür. Yetkinizi işletme hesabının yöneticisine kontrol ettirin; bağlantı göründüğünde jeton, uygulama incelemesi gerekmeden üretilir.

Sunucu olayları ne kadar gecikmeyle gönderilebilir?

Olayın zamanı gönderimden en çok yedi gün önceye ait olabilir; daha eski tek bir olay bütün isteği hataya düşürür. Meta olayların gerçekleştiği anda ya da bir saat içinde gönderilmesini önerir; iki saatten sonra performans düşebilir, 24 saati aşan gecikmede ilişkilendirme ve teslim optimizasyonu etkilenebilir.

Event Match Quality puanı kaç olmalıdır?

Event Match Quality, sunucudan gönderilen müşteri bilgisinin olayı bir Meta hesabıyla ne kadar eşleştirebildiğini 10 üzerinden gösterir ve yalnızca web olayları için hesaplanır. Meta genellikle 6,0 ve üzerini hedeflemeyi önerir; puana tıklandığında ayrıntı ve iyileştirme önerileri görülür.