Events API referansı
Kimin için: App Store Operator'a kendi kodundan veya sunucusundan event gönderen geliştiriciler ve bu sayfayı verdikleri yapay zekâ kodlama ajanları. HTTP sözleşmesinin tamamı tek sayfada, curl ile hızlı başlangıç dahil. Bir uygulamaya event takibi ekleyecekseniz bunun yerine platform rehberinden başlayın (§11): bu API'nin üzerine kurulmuş hazır tracker kodu orada.
Yapay zekâ kodlama ajanları için: önce bunu okuyun
App Store Operator Events API'sini çağırıyorsunuz: POST https://api.app-store-operator.com/v1/events ve POST https://api.app-store-operator.com/v1/identify. Kimlik doğrulama X-Write-Key header'ıyla yapılır.
Kurallar
- Yazma anahtarı. Bu sayfada hâlâ
YOUR_WRITE_KEYyazıyorsa anahtarı geliştiriciden isteyin (Dashboard → uygulama → Events → Setup; anahtaraso_wk_ile başlar). Kendiniz anahtar uydurmayın, yer tutucuyu da kodda bırakmayın. - iOS, Flutter veya React Native uygulamasına takip mi ekliyorsunuz? §11'deki platform rehberini ve oradaki tracker kodunu değiştirmeden kullanın. Kendi istemcinizi bu sayfaya göre yalnızca hiçbir rehber uymuyorsa yazın (sunucu, oyun motoru, başka bir dil).
- Her event'in kendi
event_id'si olur (UUID). Event gönderildiğinde değil, gerçekleştiğinde üretilir. Tekrar denemelerde aynısı kullanılır; böylece hiçbir şey iki kez sayılmaz. - Yalnızca ağ hatasında,
429ve5xx'te tekrar deneyin. Batch'i veevent_id'lerini koruyun;429'daRetry-Afterkadar saniye bekleyin. Diğer her durumda batch'i atın (§7). - Property değerleri düz olmalı: string, sayı, boolean veya
null. İç içe nesne veya dizi göndermeyin. - Asla göndermeyin: ad, e-posta, telefon numarası, hassas konum, IDFA veya kullanıcının yazdığı metin; ne event adında ne property'lerde ne de
user_id'de. - İşinizi canlı API'ye karşı kontrol edin. §3'teki curl komutuyla bir event gönderin ve yanıtın
accepted: 1olduğunu görün; sonra kendi kodunuzun da aynı yanıtı aldığını doğrulayın. Event'lerin Dashboard → Events → Canlı'da, ortam filtresi Tüm build'ler iken göründüğünü geliştiriciye doğrulatın.
Yazma anahtarı bilerek herkese açık tasarlandı: yalnızca tek bir uygulamaya event yazabilir. Bu yüzden uygulama kodunda durmasında sakınca yok.
1. Kısa bilgiler
| Temel URL | https://api.app-store-operator.com/v1 |
| Kimlik doğrulama | Header X-Write-Key: <your write key> |
| Event gönderme | POST /v1/events, 1–100 event'lik bir batch, gövde en fazla 1 MB |
| Kullanıcı eşleme | Bir event hem anonymous_id hem user_id taşıyorsa otomatik; ya da POST /v1/identify |
| İçerik türü | application/json, UTF-8 |
| Hız limitleri | Yazma anahtarı başına dakikada 10.000 event (Free planda 500), install başına (anonymous_id) dakikada 300 event (§9) |
| Aylık event'ler | Hesap başına, tüm uygulamalar birlikte sayılır; her ayın 1'inde (UTC) sıfırlanır. Free: ayda 25.000. Planınızın limitinin %110'u aşılınca yeni event'ler sonraki aya kadar reddedilir |
| Event adları | Uygulama başına en fazla 500 farklı ad |
| Saklama süresi | 13 ay |
2. Yazma anahtarınızı alın
- App Store Operator Dashboard'unda Uygulamalar → uygulamanız → Events → Setup'ı açın.
- Yazma anahtarını kopyalayın. Anahtar
aso_wk_ile başlar.
Her uygulamanın kendi anahtarı vardır; anahtarı yalnızca o uygulamanın event'leri için kullanın. Çalışma alanınızdaki herkes anahtarı orada görebilir.
3. Hızlı başlangıç: tek bir event gönderin
Bunu bir terminalde (macOS veya Linux) çalıştırın. Komut her çalıştığında yeni bir event_id ve o anın zamanını üretir, yani tekrar tekrar çalıştırabilirsiniz:
curl -sS https://api.app-store-operator.com/v1/events \
-H "Content-Type: application/json" \
-H "X-Write-Key: YOUR_WRITE_KEY" \
-d '{
"events": [{
"event_id": "'"$(uuidgen)"'",
"name": "integration_test",
"anonymous_id": "curl-test",
"occurred_at": "'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'",
"properties": { "source": "curl" }
}]
}'Beklenen yanıt:
{ "accepted": 1, "rejected": [], "clamped": [] }Event birkaç saniye içinde Dashboard'da Events → Canlı'da görünür. Ortam bilgisi taşımadığı için varsayılan görünümde çıkar; anonymous_id değeri curl-test olan event'i arayın.
Neden her seferinde yeni değer? Aynı event_id yalnızca bir kez saklanır; aynı ID ile ikinci kez gönderirseniz yeni bir şey görmezsiniz. 7 günden eski bir zaman gönderirseniz de onun yerine event'in bize ulaştığı zamanı yazarız.
4. Yanıtı okuyun
POST /v1/events, batch'in kendisi geçerli olduğu sürece, içindeki bazı event'ler reddedilmiş olsa bile 200 OK döner:
{
"accepted": 2,
"rejected": [
{ "index": 2, "event_id": "9a1c0d7e-2b4f-4c55-9f0e-7d3a1b2c4e5f", "code": "invalid_name", "message": "Event name must match ^[A-Za-z0-9_.:-]{1,64}$" }
],
"clamped": [
{ "index": 0, "event_id": "0b6f6a3e-3c3e-4d8a-8f6e-1f9b8a2c7d10" }
]
}accepted: saklanan event'ler; daha önce saklanmış birevent_id'nin tekrarları da buna dahildir.rejected: saklanmayan event'ler.index, event'ineventsdizisindeki sırası (0'dan başlar); event'te okunabilir bir ID yoksaevent_idnullolur;codenedenini söyler (§7.1). Bunları değiştirmeden tekrar göndermeyin.clamped:occurred_atdeğeri kabul aralığının dışında olduğu için bize ulaştığı zamanla değiştirilen event'ler. Bunlar saklanır veaccepted'a dahildir.
Üç alan da her zaman yanıtta bulunur; rejected ve clamped boş olabilir. Diğer her durum kodu isteğin tamamı için bir hatadır (§7): istekteki hiçbir şey saklanmamıştır.
5. Event nesnesi
POST /v1/events gövdesi, 1 ile 100 arasında event nesnesi içeren { "events": [ ... ] } biçimindedir. Gövdedeki veya event'teki bilinmeyen alanlar yok sayılır.
| Alan | Tür | Zorunlu | Kurallar |
|---|---|---|---|
event_id |
string (UUID) | evet | Her event için benzersiz. Event gönderildiğinde değil, gerçekleştiğinde üretin; böylece tekrar gönderilen bir batch iki kez sayılmaz. |
name |
string | evet | ^[A-Za-z0-9_.:-]{1,64}$. $ ve ardından bu karakterlerden 1–63 tanesi (örneğin $session_start) App Store Operator'a ayrılmıştır. snake_case ve nesne_eylem biçimini kullanın, örneğin paywall_viewed. Adlar büyük/küçük harfe duyarlıdır. |
anonymous_id |
string | evet | 1–128 karakter. Install başına sabit (diğer istemcilerde cihaz veya tarayıcı başına). |
user_id |
string veya null | hayır | 1–128 karakter. Sizin sisteminizdeki kalıcı kullanıcı ID'si. E-posta veya telefon numarası olamaz. |
occurred_at |
string | evet | Saat dilimi içeren ISO 8601, örneğin 2026-10-23T12:00:00.123Z. 7 gün öncesinden 5 dakika sonrasına kadar kabul edilir; dışındaysa bize ulaştığı zamanla değiştirilir (clamped). |
properties |
object | hayır | Düz nesne, en fazla 50 anahtar. Anahtar 1–64 karakter. Değer string (≤ 1024 karakter), sayı, boolean veya null olabilir. İç içe nesne veya dizi olamaz. |
context |
object | hayır | Cihaz ve build bilgileri, aşağıda. Dashboard funnel'ları bu alanlara göre filtreler ve kırılımlara ayırır. |
context
| Alan | Örnek | Not |
|---|---|---|
app_version |
"2.4.0" |
Pazarlama sürümü |
build |
"412" |
Build numarası |
os_version |
"18.1" |
|
device_model |
"iPhone16,2" |
Pazarlama adı değil, donanım kimliği |
locale |
"en_US" |
Cihazın yerel ayarı, language_REGION biçiminde |
environment |
"app_store" |
"debug", "testflight" veya "app_store". Siz Tüm build'ler'i seçmedikçe Dashboard yalnızca app_store event'lerini (ve bu alanı olmayanları) gösterir |
Her context değeri en fazla 64 karakterlik bir string olmalı. Bu kurala uymayan değerler ve tabloda olmayan anahtarlar, event reddedilmeden atılır.
Sunucu, isteğin geldiği ağ konumundan country bilgisini ekler. IP adresinin kendisi hiçbir zaman saklanmaz.
Serileştirilmiş bir event en fazla 8 KB, gövdenin tamamı en fazla 1 MB olabilir.
Tam bir event
{
"event_id": "0b6f6a3e-3c3e-4d8a-8f6e-1f9b8a2c7d10",
"name": "purchase_completed",
"anonymous_id": "C5E1B0B2-4F7A-4E0F-9C1D-2A6B7E8F9012",
"user_id": "u_81723",
"occurred_at": "2026-10-23T12:04:31.512Z",
"properties": {
"product_id": "pro_yearly",
"price": 39.99,
"currency": "USD",
"trial": true,
"coupon": null
},
"context": {
"app_version": "2.4.0",
"build": "412",
"os_version": "18.1",
"device_model": "iPhone16,2",
"locale": "en_US",
"environment": "app_store"
}
}6. Kullanıcı eşleme: POST /v1/identify
Event göndermeden bir anonim ID'yi bir kullanıcı ID'sine bağlar. Buna pek ihtiyacınız olmaz, çünkü iki ID'yi de taşıyan her event aynı işi görür. Eşleşmeyi yalnızca sunucunuz biliyorsa kullanın.
curl -sS -i https://api.app-store-operator.com/v1/identify \
-H "Content-Type: application/json" \
-H "X-Write-Key: YOUR_WRITE_KEY" \
-d '{ "anonymous_id": "curl-test", "user_id": "u_81723" }'İki alan da zorunlu; her biri 1–128 karakterlik bir string. Yanıt gövdesiz 204 No Content'tir. Bir anonim ID için ilk eşleşme geçerlidir; aynı anonim ID'ye sonradan gelen farklı kullanıcı ID'leri yok sayılır.
Hatalar /v1/events ile aynı kodları kullanır (§7): gövde JSON değilse ya da ID'lerden biri eksikse veya 1–128 karakterlik bir string değilse 400 invalid_body; ayrıca 401 invalid_write_key, 413 payload_too_large ve 429 rate_limited. Her çağrı, yazma anahtarının hız limitinden bir event sayılır.
7. Hatalar
Her hatanın gövdesi { "code": "…", "message": "…" } biçimindedir ve istekteki hiçbir şeyin saklanmadığı anlamına gelir.
| Durum | code |
Anlamı | Ne yapmalı |
|---|---|---|---|
| 400 | invalid_body |
Gövde geçerli bir JSON veya { "events": [...] } değil ya da event sayısı 0 veya 100'den fazla |
Kodu düzeltin; tekrar denemeyin |
| 401 | invalid_write_key |
Anahtar eksik, tanınmıyor veya iptal edilmiş. /v1/events bu yanıtı uygulama App Store Operator'dan kaldırıldığında, App Store Connect bağlantısı silindiğinde veya çalışma alanının hesabı devre dışı bırakıldığında da verir |
Tekrar denemeyin; batch'i atın ve Setup'taki anahtarı kontrol edin |
| 403 | quota_exceeded |
Hesap aylık event limitinin %110'unu kullandı | Tekrar denemeyin; batch'i atın. Gönderim ayın 1'inde (UTC) ya da plan yükseltilince yeniden başlar |
| 413 | payload_too_large |
Gövde 1 MB'tan büyük | Daha küçük batch'ler gönderin |
| 429 | rate_limited |
Bir hız limiti aşıldı (§9). Retry-After header'ı kaç saniye bekleneceğini söyler |
Batch'i saklayın; Retry-After kadar saniye sonra tekrar deneyin |
| 5xx | server_error |
Bizim tarafımızda bir hata | Batch'i saklayın; artan bekleme süresiyle (backoff) tekrar deneyin (örneğin 30 sn, 60 sn, 120 sn… en fazla 10 dakika) |
Tek cümlede tekrar deneme kuralı: ağ hatasında, 429 ve 5xx'te aynı event_id'lerle tekrar deneyin; diğer her durumda batch'i atın.
7.1 Event bazında ret kodları
Bunlar 200 yanıtının içinde, rejected alanında gelir. Yalnızca o event atlanır; batch'in geri kalanı saklanır.
| Kod | Ne zaman |
|---|---|
invalid_event |
events içindeki öğe bir JSON nesnesi değil |
invalid_name |
name eksik veya ^[A-Za-z0-9_.:-]{1,64}$ ile eşleşmiyor |
reserved_name |
name, $ ve ardından [A-Za-z0-9_.:-] karakterlerinden 1–63 tanesinden oluşuyor |
invalid_id |
event_id eksik veya UUID değil; anonymous_id eksik veya 1–128 karakterlik bir string değil; user_id var ama 1–128 karakterlik bir string veya null değil |
invalid_timestamp |
occurred_at eksik, okunamıyor veya saat dilimi içermiyor. (Aralık dışında olması ret sebebi değildir: clamped'e bakın) |
invalid_properties |
properties düz bir nesne değil; bir anahtar 1–64 karakter aralığının dışında; iç içe bir nesne veya dizi var; bir string 1.024 karakterden uzun |
too_many_properties |
50'den fazla property var |
event_too_large |
Serileştirilmiş event 8 KB'tan büyük |
too_many_event_names |
Uygulamada zaten 500 farklı event adı var ve bu ad yeni. Mevcut bir adı kullanın, ayrıntıyı bir property'ye koyun |
8. Sınırlar
| Sınır | Değer |
|---|---|
| İstek başına event | 1–100 |
| İstek gövdesi | 1 MB |
| Serileştirilmiş tek event | 8 KB |
| Event adı | A–Z a–z 0–9 _ . : - karakterlerinden 1–64 karakter |
| Event başına property | 50; anahtar 1–64 karakter; string değer en fazla 1.024 karakter |
anonymous_id, user_id |
1–128 karakter |
occurred_at |
7 gün öncesinden 5 dakika sonrasına kadar; dışındaysa bize ulaştığı zamanla değiştirilir |
| Uygulama başına farklı event adı | 500 |
| Dashboard kataloğunda event adı başına listelenen property anahtarı | 200 (sonrakiler saklanır ama listelenmez) |
| Hesap başına aylık event | Planınızın limiti (Free: 25.000); tüm uygulamalar birlikte sayılır, her ayın 1'inde (UTC) sıfırlanır. %80, %100 ve %110'da size e-posta göndeririz; %110'dan sonra yeni event'ler 403 quota_exceeded alır |
| Saklama süresi | 13 ay, sonra otomatik olarak silinir |
9. Hız limitleri
İki limit aynı anda geçerlidir; ikisi de bir dakika içinde kesintisiz dolar:
- Yazma anahtarı başına dakikada 10.000 event (Free planda 500), tüm install'lar birlikte. Her istekteki her event'i, reddedilenler dahil, ve her
/v1/identifyçağrısını bir event olarak sayar (identify çağrılarının limiti her planda 10.000). - Install başına dakikada 300 event, tek bir
anonymous_idiçin. O install'ın kabul edilen event'lerini sayar.
İki limitten birini aşacak bir istek 429 rate_limited alır; Retry-After header'ı saniye cinsinden bekleme süresini verir. İstekteki hiçbir şey saklanmaz ve sayılmaz. Batch'i saklayın ve o kadar saniye sonra yeniden gönderin. Event'leri batch'lemek (istek başına en fazla 100) sayılan event sayısını değiştirmez, ama istek sayısını düşük tutar.
10. Anahtarı yenileyin
Anahtarı yalnızca kötüye kullanılıyorsa yenileyin, örneğin biri bu anahtarla sahte event'ler gönderiyorsa. Anahtar zaten herkese açık; uygulamanızın içinden görülebiliyor olması yenilemek için bir neden değil.
- Setup → Anahtarı yenile'ye tıklayın. Bunu çalışma alanındaki herkes yapabilir ve işlem kayda geçer.
- Yeni anahtarı uygulamanıza koyup bir güncelleme yayınlayın.
- Eski anahtar 30 gün daha çalışır; kullanıcılarınızın güncellemeye vakti olur. Bu sürenin sonunda eski anahtarla gelen istekler
401 invalid_write_keyalır. - Eski anahtar hâlâ kötüye kullanılıyorsa Setup → Eski anahtarı şimdi iptal et ile 30 günlük süreyi hemen bitirin.
- Eski anahtarın 30 günü dolmadan Anahtarı yenile tekrar kullanılamaz. Bir daha yenilemek için önce eski anahtarı iptal edin ya da 30 günün dolmasını bekleyin.
11. Platform rehberleri
Hazır bir tracker'la (batch'leme, tekrar deneme, çevrimdışı kuyruk, onay anahtarı) adım adım entegrasyon, neyin izleneceği, gizlilik ve App Store gizlilik etiketi:
- iOS (Swift): https://app-store-operator.com/tr/docs/events/ios
- Flutter: https://app-store-operator.com/tr/docs/events/flutter
- React Native: https://app-store-operator.com/tr/docs/events/react-native
Her rehber, yapay zekâ kodlama ajanları için düz Markdown olarak da sunulur: https://app-store-operator.com/docs/events/tr/ios.md gibi.
Gizlilik soruları ve silme talepleri için: [email protected].