Postlip Metrics Tracking API

Ürünlerin Postlip Metrics'e olay göndermesi için sözleşme — Segment Tracking API Spec uyumlu (aynı uçlar, mesaj alanları ve kimlik doğrulama; Segment/RudderStack istemcileri host ayarıyla kullanılabilir). Ayrıntı ve örnekler: docs/api/tracking-api.md. Kimlik: kaynağın yazma anahtarı (pk_live_… / pk_test_…) HTTP Basic kullanıcı adı olarak, Authorization: Bearer ile ya da tarayıcı beacon'ında gövdede writeKey. Sunucu kaynakları isteği Metrics-Signature başlığıyla imzalar (kaynakta zorunlu kılınabilir). İdempotentlik: messageId — aynı gerçek olay için aynı kimliği üretin; tekrar eden mesaj bir kez saklanır.

Sürüm 1.0.0OpenAPI 3.1.0OpenAPI belgesini indir

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

Sunucular

Adres	Açıklama
`https://collect.metrics.example`	Tracking API
`http://localhost:7110`	Yerel geliştirme

Kimlik doğrulama

Ad	Yöntem	Açıklama
`writeKeyBasic`	HTTP Basic	Kullanıcı adı = yazma anahtarı, şifre boş (Segment uyumlu).
`writeKeyBearer`	Bearer belirteci (pk_…)	Yazma anahtarı.
`signature`	Başlık: Metrics-Signature	İstek imzası (sunucu kaynakları).

Sınırlar

Sınır	Değer
Mesaj boyutu	en çok 32 KB
Parti boyutu	en çok 500 KB
Partideki mesaj sayısı	en çok 500
Geçmişe dönük zaman damgası	en çok 31 gün
İleri tarihli zaman damgası	en çok 3600 sn
İmza zaman penceresi	±300 sn
userId, anonymousId, groupId uzunluğu	en çok 200 karakter
messageId uzunluğu	en çok 100 karakter
Olay adı uzunluğu	en çok 200 karakter
Düzendeki öğe sayısı ($layout)	en çok 300
Tıklama koordinatı ölçeği	0–1000 (belgenin genişlik ve yüksekliğine göre)
Kaynak başına hız sınırı	dakikada 60.000 mesaj; aşılınca 429 ve Retry-After
Kısa süreli yoğunluk payı	bir anda en çok 10.000 mesaj

Olay gönderimi

7 uç

track, identify, page, screen, group, alias ve toplu gönderim.

POST/v1/track

Olay (track)

Kullanıcının yaptığı bir eylem. event uygulamanın olay kataloğuna göre doğrulanır (strict/lenient/discover). $ ile başlayan adlar SDK sistem olaylarıdır (bkz. x-system-events).

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonTrackMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: track
`event`zorunlu	`string`	1–200 karakter
`properties`	`object`	Serbest anahtarlar

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "track",
  "event": "string",
  "properties": {}
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/identify

Kişiyi tanıt (identify)

Anonim kimliği kullanıcı kimliğine bağlar; traits kişi özellikleridir.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonIdentifyMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: identify
`traits`	`object`	Serbest anahtarlar

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "identify",
  "traits": {}
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/page

Sayfa görüntüleme (page)

Web sayfası görüntüleme. properties.url ya da context.page.url gönderin.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonPageMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: page
`name`	`string`	en çok 500 karakter
`category`	`string`	en çok 200 karakter
`properties`	`object`	Serbest anahtarlar

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "page",
  "name": "string",
  "category": "string",
  "properties": {}
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/screen

Ekran görüntüleme (screen)

Mobil uygulama ekranı.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonScreenMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: screen
`name`	`string`	en çok 500 karakter
`category`	`string`	en çok 200 karakter
`properties`	`object`	Serbest anahtarlar

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "screen",
  "name": "string",
  "category": "string",
  "properties": {}
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/group

Hesaba bağla (group)

Kişiyi bir hesaba (şirket, büro, site…) bağlar; traits hesap özellikleridir.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonGroupMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: group
`groupId`zorunlu	`string \| number`
`traits`	`object`	Serbest anahtarlar

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "group",
  "groupId": "string",
  "traits": {}
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/alias

Kimlik birleştir (alias)

previousId ile userId aynı kişidir.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonAliasMessage

Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`zorunlu	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: alias
`previousId`zorunlu	`string \| number`

Örnek · JSON

{
  "messageId": "string",
  "anonymousId": "string",
  "userId": "string",
  "timestamp": "2026-11-06T14:46:00+03:00",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  },
  "integrations": {},
  "type": "alias",
  "previousId": "string"
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

POST/v1/batch

Toplu gönderim (batch)

En fazla 500 mesaj, karışık tiplerde; her mesajda type zorunlu. Tarayıcıdan text/plain gövdeyle ve writeKey gövdede gönderilebilir (CORS ön isteği yok).

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesiGövde zorunlu

application/jsonBatchRequest

Alan	Tip	Açıklama
`batch`zorunlu	`(TrackMessage \| IdentifyMessage \| PageMessage \| ScreenMessage \| GroupMessage \| AliasMessage)[]`	1–500 öğe
`writeKey`	`string`	Yalnız tarayıcı beacon'ı için (başlık gönderilemediğinde).
`sentAt`	`string`	Biçim: date-time
`context`	`Context`	Kendi `context`'i olmayan mesajlara uygulanır.

Örnek · JSON

{
  "batch": [
    {
      "type": "track",
      "event": "string"
    }
  ],
  "writeKey": "string",
  "sentAt": "2026-11-06T14:46:00+03:00",
  "context": {
    "ip": "string",
    "userAgent": "string"
  }
}

text/plainstring

Aynı JSON, metin olarak (tarayıcı beacon).

Yanıtlar

200

İşlendi.

application/jsonTrackingResponse

Örnek · JSON

{
  "success": true,
  "accepted": 0,
  "rejected": [
    {
      "index": 0,
      "errors": [
        {
          "code": "invalid_message",
          "path": "string",
          "message": "string"
        }
      ]
    }
  ],
  "warnings": [
    {
      "index": 0,
      "code": "invalid_message",
      "path": "string"
    }
  ]
}

400
Gövde okunamadı ya da bütün mesajlar reddedildi (all_rejected, rejected listesiyle). Tekrar etmeyin.
application/jsonRefusal
401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal
403
Origin kaynağın izinli alan adlarında değil (origin_not_allowed).
application/jsonRefusal
413
Mesaj > 32 KB ya da parti > 500 KB / 500 mesaj. Partiyi bölün.
application/jsonRefusal
429
Kaynağın hız sınırı aşıldı (rate_limited; mesaj sayısıyla, varsayılan dakikada 60.000, bir anda 10.000): hiçbir mesaj saklanmadı. Retry-After saniye bekleyip aynı partiyi yeniden gönderin.
Yanıt başlıkları
- Retry-Afterinteger
  Yeniden denemeden önce beklenecek saniye.
  en az 1
application/jsonRefusal
5XX
Geçici hata: üstel geri çekilmeyle tekrar deneyin (1 dk, 5 dk, 30 dk, 2 sa… en fazla 24 sa).

Kurulum

4 uç

Bağlantı testi, SDK uzak yapılandırması, web SDK paketi, sağlık.

POST/v1/ping

Bağlantı testi

Anahtarı ve (gönderildiyse ya da kaynak istiyorsa) imzayı doğrular; hiçbir şey kaydetmez. Gövde {}.

Kimlik: writeKeyBasic ya da writeKeyBearer ya da writeKeyBasic + signature

Parametreler

Ad	Yer	Tip	Açıklama
`Metrics-Signature`	başlık	`string`	`t=<unix saniye>,v1=<hex>`; v1 = HMAC-SHA256(imza anahtarı `sk_…`, `t + "." + hamGövde`). ±300 sn. Anahtar yenilenirken birden çok `v1=` olabilir. Desen: `^t=\d{1,12}(,v1=[0-9a-fA-F]{64})+$`

İstek gövdesi

application/jsonobject

Örnek · JSON

{}

Yanıtlar

200

Anahtar (ve imza) geçerli.

application/jsonPingResponse

Örnek · JSON

{
  "success": true,
  "sourceId": "string",
  "appId": "string",
  "environment": "string",
  "test": true,
  "signature": "valid"
}

401
Anahtar yok/yanlış (missing_key, invalid_key) ya da imza (signature_required, signature_invalid, signature_expired). Anahtarı ve sunucu saatini denetleyin.
application/jsonRefusal

GET/v1/config/{writeKey}

SDK uzak yapılandırması

Panelde kaynak için yapılan yakalama ayarları (hariç yollar, rıza kipi, otomatik yakalama, örnekleme…). ttlSeconds kadar önbelleğe alınabilir; istek başarısızsa SDK varsayılanlarla çalışır.

Kimlik: Kimlik gerekmez

Parametreler

Ad	Yer	Tip	Açıklama
`writeKey`zorunlu	yol	`string`	Kaynağın yazma anahtarı (`pk_…`).
`schemaHints`	sorgu	`string`	`1`: yanıtta ayrıca `schemaHints` — uygulamanın olay planının özeti (planlanmış olaylar ve zorunlu özellikleri, engellenen olaylar, şema kipi). Web SDK debug kipinde ister; parametresiz yanıt değişmez. Değerler: 1

Yanıtlar

200

Yapılandırma.

application/jsonRemoteConfig

Örnek · JSON

{
  "sourceId": "string",
  "appId": "string",
  "kind": "web",
  "environment": "production",
  "test": true,
  "ttlSeconds": 1,
  "consentMode": "required",
  "excludedPaths": [
    "string"
  ],
  "maskSelectors": [
    "string"
  ],
  "ignoreSelectors": [
    "string"
  ],
  "stripQueryParams": [
    "string"
  ],
  "sessionTimeoutMinutes": 5,
  "interactionSampleRate": 0,
  "autocapture": {
    "pageviews": true,
    "pageleave": true,
    "clicks": true,
    "rageClicks": true,
    "deadClicks": true,
    "scroll": true,
    "errors": true,
    "forms": true,
    "layout": true,
    "outboundLinks": true,
    "downloads": true,
    "webVitals": true
  },
  "dataLayerEvents": [
    "string"
  ],
  "schemaHints": {
    "mode": "strict",
    "events": [
      {
        "name": "string",
        "required": []
      }
    ],
    "blocked": [
      "string"
    ],
    "truncated": true
  }
}

404
Anahtar tanınmadı.
application/jsonRefusal

Şemalar

İsteklerde ve yanıtlarda adıyla anılan şemalar.

`TrackingResponseobject`

TrackingResponse
Alan	Tip	Açıklama
`success`zorunlu	`boolean`	Sabit: true
`accepted`zorunlu	`integer`	Mesajlardan kabul edilenlerin sayısı (tekrar edenler dahil; tekrar eden bir kez saklanır).
`rejected`zorunlu	`object[]`	Reddedilenler. Düzeltmeden tekrar göndermeyin.
`rejected[].index`zorunlu	`integer`
`rejected[].messageId`	`string`
`rejected[].errors`zorunlu	`object[]`
`rejected[].errors[].code`zorunlu	`string`	Değerler: invalid_message, unknown_type, event_name_missing, identity_missing, event_unplanned, event_blocked, property_required, property_type, property_unplanned, property_too_long, pii_detected, timestamp_invalid, timestamp_out_of_range, message_too_large, currency_unknown, property_out_of_range
`rejected[].errors[].path`zorunlu	`string`
`rejected[].errors[].message`zorunlu	`string`
`warnings`zorunlu	`object[]`	Kabul edildi ama dikkat: planlanmamış özellik, kişisel veri maskelendi…
`warnings[].index`zorunlu	`integer`
`warnings[].code`zorunlu	`string`	Değerler: invalid_message, unknown_type, event_name_missing, identity_missing, event_unplanned, event_blocked, property_required, property_type, property_unplanned, property_too_long, pii_detected, timestamp_invalid, timestamp_out_of_range, message_too_large, currency_unknown, property_out_of_range
`warnings[].path`zorunlu	`string`

`Refusalobject`

Refusal
Alan	Tip	Açıklama
`success`zorunlu	`boolean`	Sabit: false
`error`zorunlu	`object`
`error.code`zorunlu	`string`
`error.message`zorunlu	`string`
`rejected`	`object[]`
`rejected[].index`zorunlu	`integer`
`rejected[].messageId`	`string`
`rejected[].errors`zorunlu	`object[]`
`rejected[].errors[].code`zorunlu	`string`	Değerler: invalid_message, unknown_type, event_name_missing, identity_missing, event_unplanned, event_blocked, property_required, property_type, property_unplanned, property_too_long, pii_detected, timestamp_invalid, timestamp_out_of_range, message_too_large, currency_unknown, property_out_of_range
`rejected[].errors[].path`zorunlu	`string`
`rejected[].errors[].message`zorunlu	`string`

`PingResponseobject`

PingResponse
Alan	Tip	Açıklama
`success`zorunlu	`boolean`	Sabit: true
`sourceId`zorunlu	`string`
`appId`zorunlu	`string`
`environment`zorunlu	`string`
`test`zorunlu	`boolean`
`signature`zorunlu	`string`	Değerler: valid, absent

`RemoteConfigobject`

RemoteConfig
Alan	Tip	Açıklama
`sourceId`zorunlu	`string`
`appId`zorunlu	`string`
`kind`zorunlu	`string`	Değerler: web, ios, android, server, other
`environment`zorunlu	`string`	Değerler: production, staging, development
`test`zorunlu	`boolean`
`ttlSeconds`zorunlu	`integer`	0 üstü
`consentMode`zorunlu	`string`	Değerler: required, implied, none
`excludedPaths`zorunlu	`string[]`
`maskSelectors`zorunlu	`string[]`
`ignoreSelectors`zorunlu	`string[]`
`stripQueryParams`zorunlu	`string[]`
`sessionTimeoutMinutes`zorunlu	`integer`	5–240
`interactionSampleRate`zorunlu	`number`	0–1
`autocapture`zorunlu	`object`
`autocapture.pageviews`zorunlu	`boolean`
`autocapture.pageleave`zorunlu	`boolean`
`autocapture.clicks`zorunlu	`boolean`
`autocapture.rageClicks`zorunlu	`boolean`
`autocapture.deadClicks`zorunlu	`boolean`
`autocapture.scroll`zorunlu	`boolean`
`autocapture.errors`zorunlu	`boolean`
`autocapture.forms`zorunlu	`boolean`
`autocapture.layout`zorunlu	`boolean`
`autocapture.outboundLinks`zorunlu	`boolean`
`autocapture.downloads`zorunlu	`boolean`
`autocapture.webVitals`zorunlu	`boolean`
`dataLayerEvents`zorunlu	`string[]`
`schemaHints`	`object`
`schemaHints.mode`zorunlu	`string`	Değerler: strict, lenient, discover
`schemaHints.events`zorunlu	`object[]`
`schemaHints.events[].name`zorunlu	`string`
`schemaHints.events[].required`zorunlu	`string[]`
`schemaHints.blocked`zorunlu	`string[]`
`schemaHints.truncated`zorunlu	`boolean`

`Contextobject`

Context
Alan	Tip	Açıklama
`ip`	`string`	en çok 64 karakter
`userAgent`	`string`	en çok 1000 karakter
`locale`	`string`	en çok 35 karakter
`timezone`	`string`	en çok 64 karakter
`groupId`	`string \| number`
`traits`	`object`	Serbest anahtarlar
`page`	`object`
`page.url`	`string`	en çok 4000 karakter
`page.path`	`string`	en çok 2000 karakter
`page.title`	`string`	en çok 1000 karakter
`page.referrer`	`string`	en çok 4000 karakter
`page.search`	`string`	en çok 2000 karakter
`campaign`	`object`
`campaign.source`	`string`	en çok 200 karakter
`campaign.medium`	`string`	en çok 200 karakter
`campaign.name`	`string`	en çok 300 karakter
`campaign.content`	`string`	en çok 300 karakter
`campaign.term`	`string`	en çok 300 karakter
`campaign.id`	`string`	en çok 200 karakter
`app`	`object`
`app.name`	`string`	en çok 200 karakter
`app.version`	`string`	en çok 100 karakter
`app.build`	`string`	en çok 100 karakter
`app.namespace`	`string`	en çok 300 karakter
`device`	`object`
`device.type`	`string`	en çok 50 karakter
`device.manufacturer`	`string`	en çok 100 karakter
`device.model`	`string`	en çok 100 karakter
`device.id`	`string`	en çok 200 karakter
`device.advertisingId`	`string`	en çok 200 karakter
`os`	`object`
`os.name`	`string`	en çok 100 karakter
`os.version`	`string`	en çok 100 karakter
`screen`	`object`
`screen.width`	`number`	en az 0
`screen.height`	`number`	en az 0
`screen.density`	`number`	0 üstü
`library`	`object`
`library.name`	`string`	en çok 100 karakter
`library.version`	`string`	en çok 50 karakter
`viewport`	`object`
`viewport.width`	`number`	en az 0
`viewport.height`	`number`	en az 0
`clickIds`	`object`
`clickIds.gclid`	`string`	en çok 500 karakter
`clickIds.gbraid`	`string`	en çok 500 karakter
`clickIds.wbraid`	`string`	en çok 500 karakter
`clickIds.dclid`	`string`	en çok 500 karakter
`clickIds.fbclid`	`string`	en çok 500 karakter
`clickIds.fbc`	`string`	en çok 500 karakter
`clickIds.fbp`	`string`	en çok 500 karakter
`clickIds.li_fat_id`	`string`	en çok 500 karakter
`clickIds.msclkid`	`string`	en çok 500 karakter
`clickIds.ttclid`	`string`	en çok 500 karakter
`clickIds.yclid`	`string`	en çok 500 karakter
`clickIds.gclid_at`	`string \| number`
`attribution`	`object`
`attribution.first_touch`	`object`
`attribution.first_touch.source`	`string`	en çok 200 karakter
`attribution.first_touch.medium`	`string`	en çok 200 karakter
`attribution.first_touch.campaign`	`string`	en çok 300 karakter
`attribution.first_touch.content`	`string`	en çok 300 karakter
`attribution.first_touch.term`	`string`	en çok 300 karakter
`attribution.first_touch.campaign_id`	`string`	en çok 200 karakter
`attribution.first_touch.landing_path`	`string`	en çok 2000 karakter
`attribution.first_touch.referrer_host`	`string`	en çok 300 karakter
`attribution.first_touch.at`	`string`	Biçim: date-time
`attribution.last_non_direct_touch`	`object`
`attribution.last_non_direct_touch.source`	`string`	en çok 200 karakter
`attribution.last_non_direct_touch.medium`	`string`	en çok 200 karakter
`attribution.last_non_direct_touch.campaign`	`string`	en çok 300 karakter
`attribution.last_non_direct_touch.content`	`string`	en çok 300 karakter
`attribution.last_non_direct_touch.term`	`string`	en çok 300 karakter
`attribution.last_non_direct_touch.campaign_id`	`string`	en çok 200 karakter
`attribution.last_non_direct_touch.landing_path`	`string`	en çok 2000 karakter
`attribution.last_non_direct_touch.referrer_host`	`string`	en çok 300 karakter
`attribution.last_non_direct_touch.at`	`string`	Biçim: date-time
`attribution.session_touch`	`object`
`attribution.session_touch.source`	`string`	en çok 200 karakter
`attribution.session_touch.medium`	`string`	en çok 200 karakter
`attribution.session_touch.campaign`	`string`	en çok 300 karakter
`attribution.session_touch.content`	`string`	en çok 300 karakter
`attribution.session_touch.term`	`string`	en çok 300 karakter
`attribution.session_touch.campaign_id`	`string`	en çok 200 karakter
`attribution.session_touch.landing_path`	`string`	en çok 2000 karakter
`attribution.session_touch.referrer_host`	`string`	en çok 300 karakter
`attribution.session_touch.at`	`string`	Biçim: date-time
`attribution.method`	`string`	Değerler: consent, same_visit
`consent`	`object`
`consent.analytics`zorunlu	`boolean`
`consent.marketing`zorunlu	`boolean`
`session`	`object`
`session.id`zorunlu	`string`	1–100 karakter
`session.start`	`boolean`
`tab`	`object`
`tab.id`zorunlu	`string`	1–100 karakter
`test`	`boolean`
`internal`	`boolean`
`ga`	`object`
`ga.clientId`	`string`	Desen: `^\d{1,20}\.\d{1,20}$`
`ga.sessionId`	`string`	Desen: `^\d{1,20}$`

`TrackMessageobject`

TrackMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: track
`event`zorunlu	`string`	1–200 karakter
`properties`	`object`	Serbest anahtarlar

`IdentifyMessageobject`

IdentifyMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: identify
`traits`	`object`	Serbest anahtarlar

`PageMessageobject`

PageMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: page
`name`	`string`	en çok 500 karakter
`category`	`string`	en çok 200 karakter
`properties`	`object`	Serbest anahtarlar

`ScreenMessageobject`

ScreenMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: screen
`name`	`string`	en çok 500 karakter
`category`	`string`	en çok 200 karakter
`properties`	`object`	Serbest anahtarlar

`GroupMessageobject`

GroupMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: group
`groupId`zorunlu	`string \| number`
`traits`	`object`	Serbest anahtarlar

`AliasMessageobject`

AliasMessage
Alan	Tip	Açıklama
`messageId`	`string`	Desen: `^[\x21-\x7e]{1,100}$`
`anonymousId`	`string \| number`
`userId`zorunlu	`string \| number`
`timestamp`	`string`	Biçim: date-time
`sentAt`	`string`	Biçim: date-time
`context`	`Context`
`integrations`	`object`	Serbest anahtarlar
`type`	`string`	Sabit: alias
`previousId`zorunlu	`string \| number`

`BatchRequestobject`

BatchRequest
Alan	Tip	Açıklama
`batch`zorunlu	`(TrackMessage \| IdentifyMessage \| PageMessage \| ScreenMessage \| GroupMessage \| AliasMessage)[]`	1–500 öğe
`writeKey`	`string`	Yalnız tarayıcı beacon'ı için (başlık gönderilemediğinde).
`sentAt`	`string`	Biçim: date-time
`context`	`Context`	Kendi `context`'i olmayan mesajlara uygulanır.