Ingest sözleşmesi (Chrome eklentisi)

Chrome eklentisi ve StreamEmber launcher her platform × öğe türü × dil için tek bir POST gönderir. Sunucu ham platform yanıtı kabul etmez; ayrıştırma eklentinin işidir. Platformun veri yapısı değişirse eklenti güncellenir, bu sözleşme aynı kalır. Sözleşme değişirse schema sürümü artırılır.

#Uç nokta

Eklenti host_permissions ile https://api.streamember.com/* adresine erişir; CORS gerekmez. Sunucu yine de OPTIONS isteğine X-Ingest-Token başlığına izin veren bir yanıt döner.

#Gövde

{
  "schema": "streamember.ingest/1",
  "platform": "tiktok",
  "item_type": "gift",
  "lang": "tr",
  "source": {
    "agent": "streamember-chrome-extension",
    "agent_version": "0.2.0",
    "captured_at": "2026-10-07T09:45:36Z",
    "platform_lang": "tr-TR",
    "streamer_region": "VN",
    "page_url": "https://www.tiktok.com/@ornek/live"
  },
  "items": [
    {
      "native_id": "5655",
      "name": "Gül",
      "description": null,
      "value": { "amount": 1, "unit": "tiktok_coin" },
      "icon": "https://p16-webcast.tiktokcdn.com/img/alisg/webcast-sg/…~tplv-obj.webp",
      "flags": { "community": false, "streakable": true },
      "attributes": {
        "tiktok.gift_type": 1,
        "tiktok.gift_sub_type": 0,
        "tiktok.gift_label_type": 0,
        "tiktok.is_global_gift": true,
        "tiktok.is_displayed_on_panel": true
      }
    }
  ]
}

#Alanlar

Tanımlanmamış alanlar yok sayılır. Aynı gönderimde tekrar eden native_id reddedilir; eklenti listeyi göndermeden önce tekilleştirmelidir.

#Platform eşleme rehberi

Deneme kayıtlarından (2026-10-07) çıkarılan eşleme. Sunucu yalnızca sözleşmeye bakar; bu tablo eklenti içindir.

TikTok listesi aynı hediyeyi birden fazla kez içerebilir (deneme kaydında 677 satır, 673 benzersiz hediye); ilk görülen alınır.

#Yanıt

{
  "ok": true,
  "submission_id": "sub_20261007T114856Z_34e910",
  "platform": "tiktok",
  "item_type": "gift",
  "lang": "tr",
  "received": 673,
  "created": 3,
  "updated": 12,
  "unchanged": 658,
  "rejected": [
    { "index": 41, "native_id": "99999", "errors": ["value.unit: tiktok için tiktok_coin olmalı"] }
  ]
}

Bütün isteğin reddedilmesine yalnızca zarf hataları yol açar. Öğe düzeyindeki hata sadece o öğeyi reddeder. received = created + updated + unchanged + rejected sayısı.

#Hatalar

#Aynı içerik penceresi

Aynı içerik en fazla 30 dakikada bir yazılır (config.php → ingest_duplicate_window_seconds, 0 = kapalı).

• İçerik anahtarı: platform | item_type | lang | streamer_region | öğeler. Öğeler native_id sırasına göre dizilir; yalnız native_id, name, value.amount ve description hesaba katılır. captured_at, agent ve page_url anahtara girmez.
• Böylece aynı ülkede ve aynı dilde aynı listeyi gören yüzlerce launcher yalnız bir kez yazar. Farklı ülke, dil ya da değişmiş liste ayrı içeriktir ve hemen kabul edilir.
• İşaret storage/throttle/<sha1> dosyasında, flock altında tutulur. Eşzamanlı iki aynı gönderimden yalnız biri geçer, diğeri 429 alır.
• Yazım 500 ile biterse işaret geri alınır; bir sonraki gönderim pencereyi beklemez.
• Pencereden eski işaret dosyaları ara sıra (≈ her 200 gönderimde bir) silinir.

İstemci 429'u hata olarak göstermemeli. Launcher aynı lang + streamer_region için kendi tarafında da 30 dakika bekler.

#Sunucunun yaptığı

1. Token'ı, zarfı ve her öğeyi doğrular.
2. Her öğe için:
   1. Katalogda yoksa oluşturur ve first_seen atar.
   2. Varsa dilden bağımsız alanları (value, icon, flags, attributes) son gönderimle günceller; eski değerleri storage/history/ altına yazar.
   3. Ad ve açıklamayı lang dilinin dosyasına yazar.
   4. last_seen, langs ve regions alanlarını günceller.
3. Gönderimi özetiyle storage/submissions/ altına sıkıştırılmış olarak kaydeder.
4. Hiçbir öğeyi silmez. tikfinity-import kaynağından gelen gönderim yalnızca eksikleri tamamlar.

#Launcher

Launcher, gizli canlı yayın penceresinde sayfanın kendi GET /webcast/gift/list/ yanıtını CDP ile yakalar ve yukarıdaki TikTok eşlemesiyle gönderir:

• source.agent: streamember-launcher, agent_version = uygulama sürümü.
• lang: isteğin webcast_language / app_language parametresinden. zh-TW/zh-Hant → zh-Hant, zh* → zh-Hans, diğerleri ilk alt etiket. 14 kod dışında kalırsa gönderilmez.
• source.platform_lang: ham dil parametresi. source.streamer_region: data.pages[].region.
• source.page_url: yayın sayfası.
• Gövde gzip ile gönderilir. Aynı lang + region için 30 dakikada en fazla bir istek atılır. Başarısız istek sessizce yok sayılır; yayın izlemeyi etkilemez.

Hediye listesi yalnız TikTok'a giriş yapılmış oturumda istenir. Böylece farklı ülkelerdeki launcher kullanıcıları kendi bölgelerinin listesini toplar.

#Eklenti kontrol listesi

• Platform yanıtını eklentide ayrıştır, sunucuya yalnızca bu şemayı gönder.
• Her dil için ayrı istek; lang bizim kodumuz, platformun kodu source.platform_lang.
• native_id her zaman metin; listeyi göndermeden önce tekilleştir.
• Biliniyorsa yayıncının ülkesini source.streamer_region alanına ekle.
• Platform istenen dili uygulamadıysa (ad listesi başka bir dilinkiyle aynıysa) o dili gönderme.
• Yanıttaki rejected listesini kayıt ekranında göster.