İçeriğe geç
Belgeler menüsüTracking API kılavuzu

Postlip Metrics Tracking API — v1

Ürünlerin Postlip Metrics'e olay göndermesi için sözleşme. Segment Tracking API Spec ile uyumludur: aynı uçlar, aynı mesaj alanları, aynı kimlik doğrulama. Segment ya da RudderStack istemci kütüphaneleri host/apiHost ayarı Postlip Metrics'e çevrilerek kullanılabilir; Postlip Metrics'in kendi SDK'ları (@postlip/web, @postlip/node; mobil uygulamalar için Android, iOS ve Flutter SDK'ları, §5.1) ek olarak imza, ret sebebi loglama ve şemadan tip üretimi sunar.

Bu sayfa derleme sırasında depodaki docs/api/tracking-api.md dosyasından üretilir.

  • Taban adres: https://collect.<alan>/v1 (geliştirme: http://localhost:7110/v1)
  • Makine tarafından okunur belge: openapi/tracking.json (koddan üretilir)

1. Kavramlar

KavramAçıklama
UygulamaÖlçülen ürün (ör. HukukPlus). Olay kataloğu uygulamaya aittir.
KaynakUygulamaya veri gönderen istemci: web sitesi, iOS, Android, sunucu. Her kaynağın kendi anahtarları vardır.
Yazma anahtarıpk_live_… / pk_test_… — tarayıcı ve mobilde açıkta durabilir; yalnız alım yapar.
İmza anahtarısk_live_… / sk_test_… — yalnız sunucuda; isteği imzalar.
Test anahtarı_test_ anahtarla gelen her olay is_test = true işaretlenir; ekranlar varsayılan olarak dışlar.
Olay kataloğuUygulamanın panelden tanımladığı olaylar ve özellikleri. Doğrulama kipi: strict (tanımsız → ret), lenient (kabul, "keşfedilen"), discover (kabul + taslak tanım).

2. Kimlik doğrulama

Üç yoldan biri (öncelik sırasıyla):

HTTP
Authorization: Basic base64("<writeKey>:")         # Segment uyumlu
Authorization: Bearer <writeKey>
{ "writeKey": "<writeKey>", ... }                    # yalnız tarayıcı beacon'ı (text/plain gövde)

İmza (sunucu kaynakları)

Kaynak ayarında "İmza zorunlu" açıksa imzasız istek 401 signature_required alır.

HTTP
Metrics-Signature: t=1793892559,v1=5f0c…e1a2

v1 = hex(HMAC-SHA256(signingSecret, t + "." + hamGövde)). t Unix saniyedir; sunucu saatinden ±300 sn dışındaysa 401 signature_expired. Birden çok v1= değeri (anahtar yenileme dönemi) kabul edilir.

3. Uçlar

UçMesaj tipi
POST /v1/trackKullanıcının yaptığı bir eylem
POST /v1/identifyKişiyi kullanıcı kimliğiyle tanıtma, kişi özellikleri
POST /v1/pageWeb sayfası görüntüleme
POST /v1/screenMobil ekran görüntüleme
POST /v1/groupKişiyi bir hesaba (şirket/büro/site) bağlama, hesap özellikleri
POST /v1/aliasİki kimliği birleştirme (previousId → userId)
POST /v1/batchKarışık tiplerde en fazla 500 mesaj
POST /v1/pingBağlantı testi: anahtarı ve (varsa) imzayı doğrular, hiçbir şey kaydetmez
GET /v1/config/{writeKey}SDK uzak yapılandırması (?schemaHints=1 ile olay planının özeti, aşağıda)
GET /v1/healthSağlık

POST /v1/ping gövdesi {} (imzalanır), yanıtı {"success": true, "sourceId", "appId", "environment", "test", "signature": "valid" | "absent"}; anahtar ya da imza hatasında §6'daki 401/403.

Gövde application/json; tarayıcıdan text/plain;charset=UTF-8 da kabul edilir (CORS ön isteği olmasın diye).

GET /v1/config/{writeKey}?schemaHints=1 (2026-11-08'de eklendi; geriye uyumlu — parametresiz yanıt değişmedi) yanıta schemaHints ekler: { "mode": "strict" | "lenient" | "discover", "events": [{ "name", "required": [özellik anahtarları] }], "blocked": [olay adları], "truncated": bool } — engellenmemiş tanımlar ve zorunlu özellikleri, engellenen olaylar (en çok 300'er), yalnız adlar (tip, açıklama, kişisel veri sınıfı yok). Web SDK'nın npm paketi debug kipinde ister ve tanımsız, engellenen olay ya da eksik zorunlu özellik için konsola uyarı yazar; gönderim bundan etkilenmez.

4. Mesaj alanları

Ortak alanlar (Segment Spec):

AlanTipZorunluAçıklama
typestringbatch içindetrack, identify, page, screen, group, alias
messageIdstring ≤ 100önerilirİdempotentlik anahtarı. Aynı messageId + timestamp ikinci kez yazılmaz. Gerçek olaydan belirleyici üretin (ör. purchase:<sipariş no>). Yoksa sunucu içerik özetinden üretir.
anonymousIdstring ≤ 200userId yoksaCihaz/tarayıcı kimliği
userIdstring ≤ 200anonymousId yoksaUygulamanın kendi kullanıcı kimliği. Opak olmalı; e-posta/telefon/TCKN kullanmayın.
timestampISO 8601hayırOlay anı; yoksa alım anı. 31 günden eski ya da 1 saatten ileri tarih reddedilir.
sentAtISO 8601hayırİstemcinin gönderdiği an; saat kayması düzeltmesinde kullanılır.
contextobjecthayır§5
integrationsobjecthayırHedef bazında aç/kapa: { "meta_capi": false }

Tipe özel alanlar:

TipAlanlar
trackevent (string ≤ 200, zorunlu), properties (object)
identifytraits (object)
pagename, category, properties (url, path, title, referrer, search)
screenname, category, properties — ekranın yolu properties.path (/ ile başlıyorsa: ör. Flutter rotası), yoksa / + name (2026-11-10; sayfa, giriş / çıkış ve yol raporları ekranı sayfa gibi okur)
groupgroupId (zorunlu), traits
aliaspreviousId (zorunlu), userId (zorunlu)

Standart properties (bütün olaylarda anlamlı): revenue, value, currency (ISO 4217; listede olmayan kod currency_unknown uyarısı alır), tax, net_revenue, order_id / transaction_id, plan_id, test (boolean — anahtar canlı olsa da test işaretler). Bunlar olay kataloğunda tanımlanmasa da her doğrulama kipinde (strict dahil) kabul edilir, tipleri her zaman denetlenir; olayda aynı anahtarla tanım varsa tanım geçerlidir. Liste: @postlip/contracts → STANDARD_PROPERTIES.

4.1 Kimlik özellikleri (identify; 2026-11-10'da eklendi, geriye uyumlu)

Bir kişiyi tanıtan Segment özellik adları yerleşik kişisel alanlardır: panelde tanım açmadan, her doğrulama kipinde (strict dahil) kabul edilir ve «tanımsız alanda kişisel veri» (pii_detected) sayılmaz. Değerleri olayda ve kişi profilinde saklanmaz: alımda çıkarılır, şifrelenir ve yalnız kişinin Mailing & SMS kaydına (Kişiler) şifreli yazılır. Kayıt kullanıcı kimliğiyle (userId), yoksa e-posta ya da telefonla, yoksa — misafir ödemede — tarayıcının anonymousId'siyle bulunur ya da açılır.

ÖzellikKişi kaydındaNot
emaile-postaKüçük harfe çevrilir; geçersiz adres yazılmaz.
phonecep ya da sabit telefonE.164'e çevrilir; ülke kodu yoksa Türk numaralandırması (0532 123 45 67).
firstName / first_name, lastName / last_namead, soyadname yoksa ad + soyad kişinin adı olur.
nameadTam ad.
address.streetadres
address.postalCode / address.postal_code (ya da düz postalCode)posta kodu
address.city (ya da düz city)şehirAyrıca kişi özelliği olarak da kalır.
address.country (ya da düz country)ülke (ISO 3166-1 alfa-2: TR)Ayrıca kişi özelliği olarak da kalır.
address.state—Yalnız kişi özelliği olarak kalır.
JavaScript
metrics.identify({ email: 'ayse@example.com', phone: '0532 123 45 67', firstName: 'Ayşe', lastName: 'Yılmaz',
                   address: { city: 'İzmir', postalCode: '35220', country: 'TR' } });   // misafir ödeme
metrics.identify('usr_7c1e', { email: 'ayse@example.com' });                            // üye
  • track mesajının context.traits'indeki kimlik özellikleri de kişi kaydına gider; sayfa / ekran mesajlarınınkiler yalnız atılır. Test, iç ve bot trafiği kişi açmaz.
  • Sıra: identify() aynı eylemin track()'inden (üyelik, giriş, satın alma) önce ve aynı anda çağrılır; SDK kullanıcı kimliğini sonraki mesajlara koyar. track() önce giderse olay kullanıcı kimliğisiz yazılır (kişiye yine anonim kimlikle birleşir, ama olayın kendi userId'si boş kalır). identify() her sayfada değil, yalnız gerçek bir eylemde çağrılır.
  • Misafir: kullanıcı kimliği olmayan identify() de kişi açar. Çerez rızası olmayan ziyaretçinin anonim kimliği günlüktür (ck_…) ve kişiye bağlanmaz: misafirin olaylarının segmentlere girmesi için sitenin opak, kalıcı bir misafir kimliğini userId olarak göndermesi önerilir (ör. sipariş e-postasından anahtarlı özetle türetilmiş — e-postanın kendisi değil).

İzin özellikleri (2026-11-10'da eklendi, geriye uyumlu). Kişinin sitenin kendi formunda verdiği ticari ileti onayı (ETK onay kutusu: üyelik, ödeme, hesap ayarı) kanal başına bir boolean'dır; kimlik özellikleri gibi yerleşiktir (her kipte kabul, olayda ve kişi profilinde saklanmaz) ve kişi kaydının e-posta / SMS iznine kanıtıyla yazılır (kaynak «Site (identify)», olay zamanı, sayfa — sorgu dizesi olmadan —, istemci adresinin anahtarlı özeti, özelliğin gönderildiği hâli).

ÖzellikKanaltruefalse
email_opt_in / emailOptIn (eş adları email_consent / emailConsent)e-postaizni olmayan kişide «Onaylı» (opt_in)«Onay yok»: onaylıysa none olur
sms_opt_in / smsOptIn (eş adları sms_consent / smsConsent)SMS (yalnız cep)aynıaynı
  • true / false dışındaki değer atılır ve property_type uyarısı alır; özellik hiç gönderilmezse izin değişmez.
  • İzin, identify()'ın verdiği adrese (kişi o adresi taşıyorsa), adres verilmediyse kişinin kendi adresine yazılır.
  • Ret kalır: reddetmiş (opt_out: abonelikten çıkma, şikâyet, İYS, panel), bastırılmış ya da tacir (merchant) kişinin izni bir özellikle değişmez — sitenin eski kaydındaki true abonelikten çıkmış birini yeniden abone yapmaz; yeniden onay kişi kartından ya da formdan kanıtla verilir. false İYS'ye ret olarak gitmez (işaretlenmemiş kutu ret değildir).
  • true ile verilen onay, uygulamada İYS açıksa İYS kuyruğuna girer (kaynak HS_WEB).
JavaScript
metrics.identify('misafir-Qm9vZ2xl', { email: 'ayse@example.com', phone: '+905321234567', first_name: 'Ayşe',
                   last_name: 'Yılmaz', email_opt_in: true, sms_opt_in: false });          // misafir ödeme, ETK kutusu
metrics.track('purchase_completed', { order_id: 'AJ-1001', value: 815.92, currency: 'TRY' }, 'purchase:AJ-1001');
  • Uygulamanın aynı anahtarlı tanımı iki etkisini korur: reject mesajı reddeder, hash özetini kişi profilinde tutar.
  • Metin ya da sayı olmayan değer atılır ve property_type uyarısı alır; değerler en çok 254 karakter tutulur.
  • Tarayıcının çerez rızası (context.consent) e-posta / SMS izni değildir; izin yalnız yukarıdaki izin özellikleriyle değişir. Kişi kaydı tarayıcının pazarlama rızasını ayrıca gösterir. Reklam platformlarına (Meta, TikTok) bu değerlerin yalnız SHA-256 özetleri ve yalnız pazarlama rızasıyla gider (§9). Liste: @postlip/contracts → IDENTITY_TRAITS, IDENTITY_ADDRESS_TRAITS, IDENTITY_CONSENT_TRAITS; OpenAPI x-identity-traits.
  • Çerez rızalı identify() aynı tarayıcının o günkü çerezsiz ziyaretini de (ck_…; rızadan önceki ürün görüntüleme, sepet, ödeme) kişiye bağlar — o ziyaret kullanıcı kimliği olan başka bir kişiye bağlı değilse.

5. context

Segment Spec'teki adlarla; Postlip Metrics'in kullandıkları:

AlanAçıklama
ipSunucu kaynağı son kullanıcının IP'sini iletebilir (konum ve iç trafik için). Olayla saklanmaz. Yoksa isteğin IP'si (yalnız tarayıcı/mobil kaynak). Pazarlama rızalı bir track dönüşümünde, uygulamanın Meta / TikTok hedefi varken, kullanıcı aracısıyla birlikte şifreli olarak yalnız teslim bitene kadar tutulur ve platforma gider (2026-11-10, §9): tarayıcı/mobil kaynakta bunun için yalnız isteğin adresi (güvenilen vekil zincirinden) kullanılır, mesajın kendi context.ip'si değil; sunucu kaynağında bu alan. Rızasız mesajda tutulmaz, gönderilmez.
userAgentTarayıcı / uygulama kimliği; cihaz, işletim sistemi, tarayıcı ve bot için ayrıştırılır, olayla saklanmaz. Sunucu kaynağı son kullanıcının tarayıcısınınkini (isteğin User-Agent başlığı) iletmelidir: Meta Conversions API web olayında ister. Yalnız pazarlama rızalı bir dönüşüm için, uygulamanın Meta / TikTok hedefi varken, IP adresiyle birlikte şifreli olarak teslim bitene kadar tutulur (§9).
locale, timezone
pageurl, path, title, referrer, search
campaignsource, medium, name, content, term, id — yoksa sayfa URL'sinden çıkarılır
referrer{ "type": "...", "id": "..." }
clickIdsPostlip Metrics eki: gclid, gclid_at, gbraid, wbraid, dclid, fbclid, fbc, fbp, li_fat_id, msclkid, ttclid, ttp, yclid — fbp ve ttp (2026-11-10'da eklendi) Meta ve TikTok piksellerinin _fbp / _ttp çerezindeki tarayıcı kimliğidir.
attributionPostlip Metrics eki: first_touch, last_non_direct_touch, session_touch — her biri {source, medium, campaign, content, term, campaign_id, landing_path, referrer_host, at}. Sunucu olayına tarayıcının bildirdiği kaynağı iletmek için; web SDK'da metrics.getContext() verir. Ayrıca method (2026-11-08'de eklendi): consent — temaslar ziyaretler arasında saklandı (web SDK'da pazarlama rızasıyla), same_visit — yalnız bu ziyaret (rızasız); talebin atıf görüntüsünde görünür. Başka değer atılır, ret yok.
consentPostlip Metrics eki: { "analytics": bool, "marketing": bool }. Pazarlama rızası yoksa tıklama kimlikleri saklanmaz ve hedeflere gönderilmez. Reklam platformlarına dönüşüm geri gönderiminde tıklama kimliği yalnız marketing: true açıkça gönderildiğinde kullanılır; Meta ve TikTok'a rızasız olaydan hiçbir şey gitmez (2026-11-10). Alan yoksa rıza yok sayılır — kaynağın rıza kipi none ise (uygulama rıza sormuyor) rıza var sayılır. Sunucu olayında tarayıcının bildirdiği rızayı bu alanla iletin (web SDK'da metrics.getContext() verir).
sessionPostlip Metrics eki: { "id": "...", "start": bool }
appname, version, build, namespace
devicetype (mobile, tablet… cihaz türünü belirler), manufacturer, model, id, advertisingId ve adTrackingEnabled (yalnız pazarlama rızasıyla saklanır)
networkSegment Spec (2026-11-10): wifi, cellular, bluetooth, carrier. Geçersiz değer atılır, ret yok.
installPostlip Metrics eki (2026-11-10, mobil SDK'ların $first_open'ında): kurulum kaynağı, §5.1. Geçersiz değer atılır, ret yok.
osname, version
screenwidth, height, density
libraryname, version
traitsKişi özellikleri (identify çağırmadan)
groupIdOlayın ait olduğu hesap
testtrue → test trafiği (anahtarın test kipine ek). Web SDK'da ?metrics_debug=1 bağlantısı oturum boyunca açar.
internalPostlip Metrics eki (2026-11-08'de belgelendi): true → iç trafik. Web SDK'da ?metrics_internal=1 bağlantısıyla işaretlenen tarayıcı (=0 kaldırır). Geçersiz değer atılır, ret yok.
gaPostlip Metrics eki (2026-11-08'de eklendi): { "clientId": "<rakam>.<rakam>", "sessionId": "<rakam>" } — tarayıcının _ga / _ga_<id> çerezlerinden (web SDK yalnız analitik rızasıyla okur). GA4 Measurement Protocol hedefi Postlip Metrics'in kimlikleri yerine bunları gönderir, dönüşüm GA4 oturumuna katılır; olayda yoksa oturumunun son ilettiği. Geçersiz değer atılır, ret yok.

Rızasız ziyaretçi (2026-11-08): kaynağın rıza kipi required iken analitik rızası olmayan tarayıcı mesajında (consent.analytics true değil; sunucu kaynakları hariç) sekmeye özgü anonymousId yerine günün ziyaretçi kimliği saklanır: ck_ + HMAC(günün tuzu, IP + tarayıcı + uygulama). Tuz her UTC günü rastgele üretilir ve gün bitince silinir — ertesi gün aynı tarayıcı başka ziyaretçidir, eski kimlik yeniden hesaplanamaz; IP yalnız girdidir, saklanmaz. userId gönderilmişse kişi yine onunla tanınır.

Tıklanan iletişim bağlantıları (2026-11-08): $click / $rageclick hedefi tel:, sms:, mailto: ya da WhatsApp (wa.me, api.whatsapp.com, web.whatsapp.com) bağlantısıysa saklanan hedefe tür eklenir (target.contact: phone, email, whatsapp) ve bağlantı şemasına ya da alan adına kısaltılır; $outbound WhatsApp adresi de yalnız alan adıyla saklanır. Numara ve adres hiç saklanmaz. Sistem olaylarına $pageleave.scroll_reversals (tamsayı, isteğe bağlı: yarım ekrandan büyük yön değişimi sayısı; aşırı kaydırma sinyali) eklendi; eski SDK'lar göndermez.

5.1 Mobil uygulamalar (2026-11-10'da eklendi, geriye uyumlu)

Android, iOS ve Flutter SDK'ları (packages/sdk-android, sdk-ios, sdk-flutter; varsayılan adres https://e.postlip.com) aynı uçları kullanır: POST /v1/batch (JSON, Authorization: Basic), screen, track, identify, group, alias. Kaynak türü ios ya da android'dir. Yeni sistem olayları:

OlayNe zamanpropertiesSaklandığı yer
$first_openKurulumdan sonra bir kez (analitik rızasıyla), ilk açılışın zamanıyla{}; kurulum kaynağı context.install'daevents
$app_openSoğuk açılış ve ön plana her dönüşfrom_background (boolean)events
$app_updatedSürüm ya da yapı numarası değişinceprevious_version, previous_build, version, buildevents
$crashÇökme (sonraki açılışta, çöken sürecin zamanı, kimlikleri ve oturumuyla), ANR / donma (ana iş parçacığı ≥ 5 sn), uygulamanın atlattığı yakalanmamış hata (Flutter)path, kind (crash · anr · error), fatal, type, message, stack, stack_hash, handled, thread, app_version, app_buildinteractions (exception: hata raporu ve oturumun hata sayısı)
  • Yaşam döngüsü olayları sayfa görüntülemesi gibidir: olay kataloğundan geçmez (her şema kipinde kabul, «keşfedilen» olmaz), analitik rızası olmadan da saklanır (required kipte çerezsiz sayılır); şemaları sabittir, yanlış tip property_type ile reddedilir. Rolleri yoktur — iş rolü uygulamanın kendi olay tanımlarındadır; kurulumu huni adımı ya da özel metrik olarak adıyla ($first_open) kullanın.
  • Ekran ayrılışı: SDK her ekran görüntülemesine properties.pageview_id verir ve ekrandan çıkınca / arka plana geçince $pageleave gönderir (path, pageview_id, active_ms, total_ms, final); ekranın kaydırma derinliği olmadığından max_scroll_pct artık isteğe bağlıdır (kaydırma ortalamaları yalnız bildiren görüntülemeleri sayar). Etkin süre, oturum süresi ve etkileşimli oturum ekranlar için de böyle hesaplanır.
  • $crash ve kişisel veri: SDK message ve stack'teki e-posta adreslerini, 7+ haneli rakam dizilerini, sorgu dizelerini ve kullanıcı dizinlerini cihazda temizler; alım ayrıca kişisel veri taramasından geçirir (pii_detected uyarısı). stack_hash (satır ve adres içermeyen çerçevelerin SHA-256'sı) aynı çökmeyi sürümler arasında gruplar ve taranmaz.
  • Kurulum kaynağı (context.install, yalnız $first_open):
    JavaScript
    { "installer": "google_play",
      "referrer": "utm_source=google&utm_medium=cpc&utm_campaign=bahar&gclid=Cj0KCQ",
      "referrerClickAt": "2026-11-10T09:10:00Z", "installBeginAt": "2026-11-10T09:11:00Z" }
    { "installer": "app_store",
      "appleSearchAds": { "attribution": true, "orgId": 1234567, "campaignId": 542370539, "adGroupId": 542317095,
                          "keywordId": 87675432, "adId": 542317136, "countryOrRegion": "TR", "conversionType": "Download" } }

    referrer Google Play kurulum yönlendiricisidir (URL sorgu biçimi, gerekirse bir kez daha kodlanmış): utm_*'ı olayın kampanyası olur — açılış adresindeki gibi; (not set) atılır —, tıklama kimlikleri (gclid…) yalnız pazarlama rızasıyla saklanır; dizenin kendisi saklanmaz. appleSearchAds AdServices'in atıf kaydıdır (SDK cihazda çözer, belirteç gönderilmez): attribution: true ise kampanya apple_search_ads / cpc, kampanya kimliği utm_campaign ve utm_id (içe aktarılmış kampanyaya kimlikle eşleşir), reklam grubu utm_content, anahtar kelime utm_term. $first_open ilk açılışın zamanını taşıdığından (sonra gelse de) oturumun teması olur, atıf modelleri kurulumu ilk temas sayar. installer: google_play, app_store, testflight ya da yükleyen paket.

  • Rıza: mobil SDK'lar web SDK'sının kiplerini izler. Analitik rızası olmadan kimlik, oturum ve kuyruk yalnız bellekte tutulur (her açılış yeni anonim ziyaretçi; required kipte sunucu günlük çerezsiz kimliği koyar), $first_open, $app_updated ve çökme yakalama çalışmaz. Reklam kimliği (GAID / IDFA) yalnız pazarlama rızasıyla, iOS'ta ayrıca ATT izniyle gönderilir; rızasız mesajda saklanmaz.
  • User-Agent mobil SDK'ların kendi biçimindedir (PostlipMetrics/0.1.0 (Linux; Android 14; Mobile), PostlipMetrics/0.1.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X)): işletim sistemi ve cihaz türü ondan ve context.os / context.device'tan okunur, tarayıcı boş kalır.

6. Yanıtlar

JSON
200
{
  "success": true,
  "accepted": 2,
  "rejected": [
    {
      "index": 2,
      "messageId": "purchase:9f2c",
      "errors": [
        { "code": "property_required", "path": "properties.plan_id", "message": "plan_id zorunlu" }
      ]
    }
  ],
  "warnings": [
    { "index": 0, "code": "property_unplanned", "path": "properties.color" }
  ]
}
KodAnlamİstemci ne yapar
200Parti işlendi. Reddedilenler rejected[]'de; düzeltmeden tekrar göndermeyin. Tekrar eden messageId kabul sayılır.Reddedileni logla.
400Gövde hiç okunamadı ya da bütün mesajlar geçersizLogla, tekrar etme.
401Anahtar yok/yanlış, imza yok/yanlış/süresi geçmişAnahtarı ve sunucu saatini denetle; tekrar dene + alarm.
403Kaynak kapalı ya da Origin izinli alan adlarında değilLogla.
413Mesaj > 32 KB ya da parti > 500 KB / 500 mesajPartiyi ikiye böl.
429Hız sınırı (kaynak başına, mesaj sayısıyla; gövde {"success": false, "error": {"code": "rate_limited", …}}, hiçbir mesaj saklanmadı)Retry-After (saniye) kadar bekle, aynı partiyi tekrar gönder.
5xx / ağ hatasıGeçiciÜstel geri çekilme: 1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa.

Hız sınırı kaynak başınadır ve mesajları sayar (500 mesajlık parti 500 sayılır): sürekli dakikada 60.000, bir anda 10.000 mesaj (kurulumun ayarı). Aşan istek hiçbir şey saklamadan 429 alır; Retry-After beklenip aynı messageId'lerle tekrar gönderilir. OpenAPI belgesinde (tracking.json) 429 yanıtının gövdesi (Refusal) ve Retry-After başlığı tanımlı, varsayılan sınırlar x-limits'te rateLimitPerMinute ve rateLimitBurst (2026-11-08).

Uygulamanın trafik filtresi kuralları (panelde Ayarlar; ör. test kampanyası adları, ofis IP aralığı, QA kullanıcı kimliği, test hesabı groupId) eşleşen mesajı test, iç ya da bot trafiği işaretler; mesaj yine kabul edilir (200), ekranlar varsayılan olarak dışlar. Her uygulamaya hazır kurallar eklenir (reklam etiket test araçlarından gelen ziyaret, test / qa_ ile başlayan ya da _test ile biten kampanya adı → test; Postlip Metrics panelinden gelen ziyaret → iç), uygulama bunları düzenleyebilir ya da silebilir. Saklanan alanlara bakan kural (IP ve tarayıcı kimliği hariç) uygulamanın geçmiş trafiğini de arka planda yeniden işaretler; işaret yalnız eklenir (2026-11-08).

Hata kodları (errors[].code): invalid_message, event_name_missing, identity_missing, event_unplanned (strict), event_blocked, property_required, property_type, property_unplanned (strict), property_too_long, pii_detected, timestamp_out_of_range, message_too_large.

Uyarı kodları (warnings[].code; mesaj kabul edilmiştir): yukarıdaki kodların reddetmeyen kipteki karşılıkları (ör. property_unplanned, pii_detected) ve currency_unknown — properties.currency ISO 4217 listesinde değil; tutar saklanır ama kur bulunamadığı için uygulamanın para birimine çevrilmeyebilir (2026-11-08'de eklendi; geriye uyumlu) — ve property_out_of_range — sayı tanımın minimum / maximum aralığının dışında; değer saklanır (aykırı tutar işaretlenir, kaybolmaz). Bu sürümden önce aralık dışı sayı strict kipte reddediliyor, diğer kiplerde atılıyordu; artık her kipte uyarıyla kabul edilir (2026-11-08; daha geniş kabul, istemci değişikliği gerekmez). Kabul edilen mesajların uyarıları örneklenerek (istek başına en çok 20, kaynak ve dakika başına en çok 600) 7 gün saklanır: panelin canlı olay akışında mesajın yanında ve kaynak sağlığında (warningsLast24h) görünür.

7. Örnekler

7.1 Sunucudan kayıt olayı (imzalı)

Bash
BODY='{"userId":"usr_7c1e","event":"signup_completed","messageId":"signup:7c1e","timestamp":"2026-11-06T14:46:00+03:00","properties":{"signup_method":"email","plan_id":"pro"},"context":{"consent":{"analytics":true,"marketing":true},"attribution":{"first_touch":{"source":"google","medium":"cpc","campaign":"hp_search_brand","landing_path":"/","at":"2026-11-02T10:11:00Z"}},"clickIds":{"gclid":"Cj0KCQiA…"}}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -X POST https://collect.<alan>/v1/track \
  -u "$WRITE_KEY:" -H "Content-Type: application/json" \
  -H "Metrics-Signature: t=$T,v1=$SIG" -d "$BODY"

7.2 Toplu gönderim

JSON
POST /v1/batch
{
  "batch": [
    { "type": "identify", "userId": "usr_7c1e", "anonymousId": "a1b2c3", "traits": { "plan": "pro" } },
    { "type": "group", "userId": "usr_7c1e", "groupId": "acc_903427", "traits": { "team_size": "6-20" } },
    { "type": "track", "userId": "usr_7c1e", "event": "purchase_completed", "messageId": "purchase:HP9f2c",
      "properties": { "transaction_id": "HP9f2c", "plan_id": "pro", "revenue": 5197.6, "net_revenue": 4331.33,
                      "tax": 866.27, "currency": "TRY", "billing_period": "yearly" } }
  ]
}

7.3 Tarayıcı (script etiketi)

HTML
<script>
  !function(){var m=window.metrics=window.metrics||[];if(m.load)return;m.q=[];["page","track","identify","group","alias","reset","consent","ready"].forEach(function(k){m[k]=function(){m.q.push([k].concat([].slice.call(arguments)))}});
  var s=document.createElement("script");s.async=1;s.src="https://collect.<alan>/m.js";document.head.appendChild(s);
  m.load=function(k,o){m.q.unshift(["load",k,o])};}();
  metrics.load("pk_live_…", { consent: "required" });
  metrics.page();
</script>

7.4 Segment istemcisiyle

JavaScript
import { Analytics } from '@segment/analytics-node';
const analytics = new Analytics({ writeKey: 'pk_live_…', host: 'https://collect.<alan>', path: '/v1/batch' });
analytics.track({ userId: 'usr_7c1e', event: 'trial_started', properties: { plan_id: 'pro', trial_days: 14 } });

(İmza zorunlu kaynaklarda Segment istemcisi imza atamaz; Postlip Metrics SDK'sını ya da imzasız sunucu kaynağı kullanın.)

8. Olay tasarımı önerileri

  • Olay adı geçmiş zamanlı ve nesne + eylem: signup_completed, trial_started, purchase_completed, demo_requested. Ad bir kez yayımlandıktan sonra değiştirilmez; yeniden adlandırma panelde takma adla yapılır.
  • Her iş olayını panelde bir iş rolüne bağlayın (signup, purchase, lead…). Dashboard, huniler, reklam ROAS'ı ve dönüşüm geri gönderimi role bakar.
  • Para: revenue vergi dahil brüt, net_revenue vergi hariç, tax vergi, currency zorunlu.
  • Gelir yalnız purchase (Satın alma) ve subscription_renewal (Abonelik yenileme) rolündeki olaylardan sayılır; refund rolündekiler düşülür. Ürün görüntüleme, sepete ekleme ya da ödeme başlangıcı olaylarındaki revenue / value olayda saklanır ama gelire girmez; rol sonradan verilir ya da kaldırılırsa geçmiş de yeniden hesaplanır.
  • Olay özelliklerinde kişisel veri göndermeyin. Kişiyi tanıtan e-posta, telefon, ad ve adres için identify()'ın kimlik özelliklerini kullanın (§4.1: kişi kaydına şifreli gider, Meta / TikTok eşleşmesinde özetleri kullanılır); başka bir kişisel alan gerekirse panelde personal + hash olarak tanımlayın — Postlip Metrics özetler, ham değeri saklamaz.
  • Aynı gerçek olay için aynı messageId'yi üretin (ödeme sağlayıcının geri çağrısı iki kez gelse de tek olay).
  • E-ticaret olaylarında Segment'in adlarını ve alanlarını kullanın (Product Viewed / product_viewed, Order Completed; products[] içinde sku ya da product_id, price, quantity; value, currency, order_id, aramada query): Meta ve TikTok hedeflerinin varsayılan olay eşlemesi bu adları tanır ve içerik alanlarını bunlardan kurar (§9).

9. Reklam platformlarına dönüşüm gönderimi ve pikselle tekilleştirme (2026-11-10)

Panelde Entegrasyonlar → Dönüşüm hedefleri'nde tanımlanan Meta Conversions API ve TikTok Events API hedefleri, olayları olay adına ya da iş rolüne göre eşler (varsayılanlar Segment e-ticaret adları: Product Viewed → ViewContent, Order Completed / purchase_completed → Purchase…) ve yalnız olayın pazarlama rızasıyla gönderir. Giden kimlikler: fbc / fbp, ttclid / ttp, kullanıcı kimliğinin (yoksa kişinin) SHA-256 özeti ve kişinin Mailing kaydındaki e-posta, telefon, ad, şehir, posta kodu, ülkenin SHA-256 özetleri (§4.1), ziyaretçinin IP adresi ve tarayıcının userAgent'ı (Meta client_ip_address / client_user_agent, TikTok user.ip / user.user_agent; 2026-11-10). IP adresi ve kullanıcı aracısı yalnız teslim bitene kadar şifreli tutulur, sonra silinir; olayda, oturumda, kişide, günlükte ve panelde yer almaz. Pazarlama rızası yoksa hiçbiri tutulmaz ve hiçbir şey gönderilmez. Sitenin gizlilik politikası, pazarlama rızası verenlerin IP adresinin ve tarayıcı bilgisinin bu platformlarla paylaşıldığını söylemelidir.

Sitenin kendi pikseli de aynı olayı gönderiyorsa platform ikisini olay kimliğiyle tekilleştirir. Postlip Metrics'in olay kimliği mesajın messageId'sidir; pikselde aynısını verin:

JavaScript
// 1) Kimliği siz seçin (önerilir: siparişten belirleyici, sunucu kopyası da aynısını taşır).
const id = 'purchase:' + order.id;
metrics.track('purchase_completed', { order_id: order.id, value: 240, currency: 'TRY', products }, id);
fbq('track', 'Purchase', { value: 240, currency: 'TRY' }, { eventID: id });
ttq.track('Purchase', { value: 240, currency: 'TRY' }, { event_id: id });

// 2) Ya da web SDK'nın ürettiğini kullanın: track() mesajın kimliğini döner (yapılandırma gelmeden yapılan çağrıda da).
const viewId = metrics.track('product_viewed', { sku: 'KUPA-1', price: 120, currency: 'TRY' });
fbq('track', 'ViewContent', { content_ids: ['KUPA-1'] }, { eventID: viewId });
ttq.track('ViewContent', { content_id: 'KUPA-1' }, { event_id: viewId });
  • Sunucudan gönderilen olayda (@postlip/node, Segment istemcisi) messageId'yi aynı biçimde verin ve tarayıcının bağlamını iletin: context olarak metrics.getContext() (rıza, temaslar, tıklama ve tarayıcı kimlikleri) ve isteğin User-Agent başlığı context.userAgent, ziyaretçinin IP adresi context.ip (sunucunun kendi adresi gönderilmez). Bağlamsız sunucu olayı rızasız sayılır ve Meta / TikTok'a gitmez (kaynağın rıza kipi none değilse).
  • Meta tekilleştirmeyi olay adı + event_id ile 48 saat içinde, TikTok piksel kodu + olay + event_id ile yapar.