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
2. Kimlik doğrulama
Üç yoldan biri (öncelik sırasıyla):
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.
Metrics-Signature: t=1793892559,v1=5f0c…e1a2v1 = 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
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):
Tipe özel alanlar:
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.
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' }); // üyetrackmesajınıncontext.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ı eylemintrack()'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 kendiuserId'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ğiniuserIdolarak 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).
true/falsedışındaki değer atılır veproperty_typeuyarı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ındakitrueabonelikten çı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). trueile verilen onay, uygulamada İYS açıksa İYS kuyruğuna girer (kaynakHS_WEB).
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:
rejectmesajı reddeder,hashözetini kişi profilinde tutar. - Metin ya da sayı olmayan değer atılır ve
property_typeuyarı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; OpenAPIx-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ı:
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ı:
- 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 (
requiredkipte çerezsiz sayılır); şemaları sabittir, yanlış tipproperty_typeile 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_idverir ve ekrandan çıkınca / arka plana geçince$pageleavegönderir (path,pageview_id,active_ms,total_ms,final); ekranın kaydırma derinliği olmadığındanmax_scroll_pctartı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. $crashve kişisel veri: SDKmessagevestack'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_detecteduyarı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" } }referrerGoogle 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.appleSearchAdsAdServices'in atıf kaydıdır (SDK cihazda çözer, belirteç gönderilmez):attribution: trueise kampanyaapple_search_ads/cpc, kampanya kimliğiutm_campaignveutm_id(içe aktarılmış kampanyaya kimlikle eşleşir), reklam grubuutm_content, anahtar kelimeutm_term.$first_openilk 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,testflightya 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;
requiredkipte sunucu günlük çerezsiz kimliği koyar),$first_open,$app_updatedve çö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-Agentmobil 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 vecontext.os/context.device'tan okunur, tarayıcı boş kalır.
6. Yanıtlar
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" }
]
}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ı)
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
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)
<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
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:
revenuevergi dahil brüt,net_revenuevergi hariç,taxvergi,currencyzorunlu. - Gelir yalnız
purchase(Satın alma) vesubscription_renewal(Abonelik yenileme) rolündeki olaylardan sayılır;refundrolündekiler düşülür. Ürün görüntüleme, sepete ekleme ya da ödeme başlangıcı olaylarındakirevenue/valueolayda 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 paneldepersonal+hasholarak 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çindeskuya daproduct_id,price,quantity;value,currency,order_id, aramadaquery): 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:
// 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:contextolarakmetrics.getContext()(rıza, temaslar, tıklama ve tarayıcı kimlikleri) ve isteğinUser-Agentbaşlığıcontext.userAgent, ziyaretçinin IP adresicontext.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 kipinonedeğilse). - Meta tekilleştirmeyi olay adı +
event_idile 48 saat içinde, TikTok piksel kodu + olay +event_idile yapar.