TikTok Pixel ve Events API Kurulumu: E-Ticaret İçin Adım Adım

TikTok Events API nedir, Pixel'den farkı ne?

TikTok Events API, dönüşüm olaylarını ziyaretçinin tarayıcısı yerine sizin sunucunuzdan veya e-ticaret platformunuzdan TikTok'a gönderen sunucudan sunucuya bir bağlantıdır. Pixel ise sitenize eklenen JavaScript koduyla tarayıcıda çalışır. İkisi rakip değil, birbirini tamamlayan iki kanaldır.

Pixel'in zayıf noktası tarayıcıya bağımlı olmasıdır: reklam engelleyiciler, çerez kısıtları, yavaş yüklenen teşekkür sayfası veya ödeme sonrası kapanan sekme, satın alma olayının hiç ulaşmamasına yol açabilir. Sunucu tarafında oluşan sipariş kaydı ise bu engellerden etkilenmez. TikTok'un kendi kurulum rehberi de Pixel'i kaldırmanızı değil, Events API'yi ikinci kanal olarak eklemenizi ve olayları tekilleştirmenizi önerir.

Aynı mantığı Meta tarafında kurduysanız süreç size tanıdık gelecek; farklar için Meta Conversions API kurulum rehberimize bakabilirsiniz.

Hangi kurulum yöntemini seçmelisiniz?

Shopify, WooCommerce gibi bir altyapı kullanıyorsanız önce platformun resmi TikTok entegrasyonunu kullanın; kendi yazılımınız varsa doğrudan API entegrasyonu veya bir etiket yöneticisi/sunucu tarafı etiketleme çözümü devreye girer. TikTok bu üç yolu ticaret iş ortakları, veri iş ortakları ve doğrudan entegrasyon olarak sınıflandırır.

Shopify'da veri paylaşımı seviyeleri

Shopify'daki TikTok uygulamasında üç veri paylaşımı seviyesi vardır ve Events API yalnızca ikisinde açıktır:

• Standart: Yalnızca TikTok Pixel. Reklam engelleyiciler veri toplamayı etkileyebilir.
• Gelişmiş (Enhanced): Pixel + Events API + Gelişmiş Eşleştirme.
• Maksimum: Bunlara ek olarak Shopify API'leri ve uygulama içi Shopify ödemesi (TikTok'a göre beta aşamasında ve tüm reklamverenlere açık değil).

Karar kuralı: Mağazanız Shopify'daysa ve uygulamada seviye “Standart” görünüyorsa, önce onu Gelişmiş'e çekin. Ayrı bir sunucu entegrasyonu kurmadan önce çoğu mağaza için bu tek ayar yeterlidir. Uygulamanın yanına elle ikinci bir Pixel kodu eklemeyin; aynı olay iki farklı kaynaktan farklı event_id ile gelir ve tekilleştirilemez.

TikTok Pixel ve Events API adım adım nasıl kurulur?

Kurulum Events Manager'da bir Pixel oluşturmakla başlar; ardından Pixel koduyla tarayıcı olaylarını, erişim jetonuyla (access token) sunucu olaylarını bağlarsınız. Platform uygulaması kullanıyorsanız 1, 2 ve 5. adımlar yeterlidir; doğrudan entegrasyonda tüm adımlar sizindir.

1. Pixel oluşturun TikTok Reklam Yöneticisi'nde Araçlar (Tools) > Events Manager > Connect Data Source > Web yolunu izleyin ve sitenizin adresini girin. Pixel adını alan adınıza göre verin.
2. Bağlantı yöntemini seçin Shopify veya Google Tag Manager gibi bir iş ortağıyla bağlanın ya da kodu elle kurun.
3. Erişim jetonu üretin Pixel'in Ayarlar (Settings) sekmesindeki Events API bölümünde “Generate Access Token” ile jeton oluşturun. Jetonu tarayıcı koduna veya herkese açık bir depoya koymayın; sunucuda ortam değişkeni olarak saklayın.
4. Sunucu olaylarını gönderin Her olayda event adı, Unix zaman damgası olarak event_time, event_id, sayfa adresi ve eşleşme anahtarlarını (ttclid, _ttp, hash'lenmiş e-posta/telefon, IP, user agent) iletin.
5. Test edip yayına alın Events Manager'daki Test Events sekmesinde tarayıcı ve sunucu olaylarını ayrı ayrı görün, ardından Genel Bakış'ta bağlantı yönteminin “server & browser” olduğunu doğrulayın.

Hangi standart etkinlikleri göndermelisiniz?

Bir e-ticaret sitesi için asgari set ViewContent, AddToCart, InitiateCheckout ve Purchase'tır; bunlara değer ve para birimi taşıyan parametreler eklenmelidir. TikTok'un Nisan 2026'da güncellenen standart etkinlik sayfası satın alma için Purchase olayını listeliyor.

Eski kurulumlarda CompletePayment veya PlaceAnOrder adlarını görebilirsiniz. TikTok, 1 Mayıs 2025'ten itibaren CompletePayment'ın adını Purchase olarak değiştirdi; eski adla gelen olaylar arka planda otomatik dönüştürüldüğü için mevcut kodunuz çalışmaya devam eder. PlaceAnOrder ve ClickButton ise 2027'ye kadar desteklenecek, ardından kullanımdan kalkacak. Yeni kurulumda Purchase kullanın, PlaceAnOrder kullanıyorsanız geçişi 2027'den önce planlayın.

Katalog reklamı kullanacaksanız content_ids değeri katalogdaki ürün kimliğiyle birebir aynı olmalı; aksi halde olay reklamla eşleşse bile ürünle eşleşmez. value alanına kargo ve vergi dahil mi hariç mi yazdığınıza bir kez karar verin ve her kanalda aynı kuralı uygulayın; ROAS hesabınız buna bağlıdır (ayrıntı için ROAS nedir yazısına bakın).

event_id ile tekilleştirme nasıl çalışır?

Pixel ve Events API aynı satın almayı aynı event adı ve aynı event_id ile gönderdiğinde TikTok ikisini tek dönüşüm sayar ve ilk gelen olayı kaydeder. event_id eksikse ya da iki kanalda farklıysa aynı sipariş iki kez raporlanır.

TikTok'un yardım merkezine göre kurallar şöyle: Yalnızca Pixel'den veya yalnızca Events API'den gelen aynı event ve event_id'li olaylar, ilk olaydan itibaren 48 saat içinde tekilleştirilir. Pixel ile Events API çakıştığında ise TikTok, ilk olaydan 5 dakika sonra ve 48 saat içinde gelen eşleşen olayları birleştirdiğini veya tekilleştirdiğini belirtir. İlk 5 dakika için ayrı bir kural açıklanmadığından pratik kural basittir: sunucu olayını gecikmeden gönderin, ilk olaydan sonra 48 saati asla geçirmeyin.

Örnek: 10482 numaralı sipariş

Müşteri 1.250 TL'lik bir sipariş verdi. Teşekkür sayfasındaki Pixel olayı ve sipariş kaydı oluştuğunda sunucunuzun gönderdiği olay şöyle eşleşmeli:

• Pixel: event = Purchase, event_id = order_10482, value = 1250, currency = TRY
• Events API: event = Purchase, event_id = order_10482, value = 1250, currency = TRY

Sipariş numarasını temel almak en güvenli yoldur, çünkü hem tarayıcı hem sunucu aynı değeri bilir. Rastgele üretilen bir kimlik kullanıyorsanız onu tarayıcıda oluşturup sunucuya (örneğin gizli bir form alanı veya veri katmanı ile) taşımanız gerekir. Sepete ekleme gibi siparişten önce gelen olaylarda sepet kimliği ile zaman damgasını birleştirmek işe yarar.

Eşleşme kalitesini (EMQ) nasıl yükseltirsiniz?

Events Manager'daki Olay Eşleşme Kalitesi (Event Match Quality, EMQ) puanı, gönderdiğiniz eşleşme anahtarlarının kapsamının ağırlıklı ortalamasıdır; ne kadar çok olayda ne kadar çok anahtar varsa puan o kadar yükselir. Meta'daki EMQ'nun TikTok karşılığıdır ve Genel Bakış (Overview) sekmesinde her olay için ayrı görünür.

TikTok'un Events API için saydığı eşleşme anahtarları şunlardır: TikTok tıklama kimliği (ttclid), _ttp birinci taraf çerezi, e-posta ve telefon (Gelişmiş Eşleştirme), external_id (üyelik veya müşteri numarası gibi kendi kimliğiniz), IP adresi ve user agent. Pixel IP ve user agent'ı kendiliğinden paylaşır; Events API'de bunları elle eklemeniz gerekir.

• E-postayı boşluklardan arındırıp küçük harfe çevirin, sonra SHA-256 ile hash'leyin.
• Telefonu ülke koduyla yazın, boşluk, tire ve baştaki sıfırı silin (0532 123 45 67 → +905321234567), sonra hash'leyin.
• external_id olarak müşteri numarasını hash'leyerek gönderin; üye girişi olan sitelerde eşleşmeye ciddi katkı verir.
• ttclid ve _ttp çerez değerini ham haliyle gönderin; bunlar hash'lenmez.
• Sunucu olayına ziyaretçinin gerçek IP'sini ve user agent'ını ekleyin, sunucunuzun kendi IP'sini değil.
• Pixel tarafında Otomatik Gelişmiş Eşleştirme'yi açmayı değerlendirin; form alanlarındaki e-posta ve telefonu tarayıcıda hash'leyerek gönderir.

Sağlık veya finans gibi hassas sektörlerde hangi alanın paylaşıldığını tek tek kontrol edebildiğiniz manuel eşleştirme daha güvenli bir tercihtir. KVKK kapsamında aydınlatma metninizin bu veri paylaşımını kapsadığını ve çerez onayı alınmadan Pixel'in tetiklenmediğini hukuk danışmanınızla birlikte kontrol edin.

Kurulumu nasıl test edersiniz, hangi hatalar sık görülür?

Test için Events Manager'daki Test Events sekmesini, TikTok Pixel Helper tarayıcı eklentisini ve Tanılama (Diagnostics) sekmesini birlikte kullanın. Test Events canlı bir test ortamı sunar ve tarayıcı ile sunucu olaylarını ayrı ayrı filtrelemenize izin verir.

1. Test Events sekmesini açın ve sunucu isteklerinize buradaki test kodunu (test_event_code) ekleyin.
2. Sitede gerçek bir akış yürütün: ürün sayfası, sepete ekleme, ödeme ve test siparişi.
3. Her olayın hem tarayıcıdan hem sunucudan geldiğini, event_id'lerin aynı olduğunu kontrol edin.
4. Canlıya aldıktan sonra Genel Bakış'ta bağlantı yöntemini (“browser only”, “server only” veya “server & browser”), EMQ puanını ve son alınma saatini izleyin.
5. Tanılama sekmesinde çıkan sorunlarda “Learn more” bağlantısı sorunun etkisini, düzeltme adımlarını ve etkilenen örnek olayları gösterir.

Kurulum doğru olsa bile TikTok'un raporladığı satın alma sayısı Shopify'daki sipariş sayısıyla bire bir tutmaz; ilişkilendirme penceresi ve görüntüleme sonrası dönüşümler farkı açıklar. Kanalları aynı tabloda karşılaştırmak için Marpany'nin dönüşüm analizi ekranı TikTok, Meta ve Google verisini mağaza siparişleriyle yan yana gösterir.

Kurulumdan sonra ilk hafta ne yapmalısınız?

İlk hafta amacınız veri akışını doğrulamak ve kampanya optimizasyonunu doğru olaya bağlamaktır; teklif ve bütçe değişikliklerini bu doğrulamadan sonra yapın.

• Gün 1: Test Events'te temel olayların iki kanaldan geldiğini ve event_id'lerin eşleştiğini doğrulayın.
• Gün 2–3: TikTok'taki Purchase sayısını aynı günlerin sipariş sayısıyla karşılaştırın; çift sayım var mı bakın.
• Gün 3–5: EMQ puanı düşükse eksik eşleşme anahtarlarını tamamlayın.
• Gün 7: Web dönüşüm kampanyalarınızın optimizasyon olayı olarak Purchase'ı seçtiğini kontrol edin.
• Sürekli: Tema, ödeme sayfası veya uygulama güncellemesinden sonra Test Events kontrolünü tekrarlayın.

TikTok'ta kampanya yapısı, hedefleme ve kreatif tarafını da gözden geçirmek isterseniz TikTok reklamları rehberimiz iyi bir başlangıç noktasıdır.