Ayrıntılı referans

Bu sayfa platform-events API'sinin tam referansıdır: taksonomi, platform eventleri, dil kuralları, veri standardı, dosya düzeni ve sunucu notları. Kısa kullanım için API.md, Chrome eklentisi için INGEST.md.

#Kimlikler

• Ayırıcı noktadır. Segmentler [a-z0-9_], son segment (native_id) [A-Za-z0-9_-].
• Kimlikler kalıcıdır: bir kez yayınlanan kimlik değiştirilmez ve başka bir şey için kullanılmaz.
• native platformun kendi adına yakın tutulur (super_chat, cheer); ortak anlam kind alanındadır.

#Seçici sözdizimi (tetikleyiciler için öneri)

API seçici çözmez; aynı filtreler ?id=, ?kind=, ?category=, ?platform= ile sorgulanabilir.

#Kategoriler ve kanonik türler

7 kategori: audience (izleyici), chat (sohbet), support (destek), membership (üyelik), moderation (moderasyon), stream (yayın), interaction (etkileşim).

Aşamalı olaylar (anket, battle, hype train, hediye kombosu) katalogda tek event olarak durur. Aşama (start, progress, end), kombo ve beğeni paketi bilgisi EventFabric'in canlı eventlerinde taşınır. Katalog kombo için yalnızca flags.streakable bilgisini verir.

#Platform eventleri

Aşağıdaki listeler data/platforms/*.json dosyalarından üretilmiştir. YouTube'da kanal aboneliği follow, kanal üyeliği subscribe türündedir. Facebook tepkileri like türündedir.

#TikTok (tiktok)

Öğe türleri: gift · birim: tiktok_coin

#YouTube (youtube)

Öğe türleri: gift · birim: youtube_jewel

#Twitch (twitch)

Öğe türleri: power_up · birim: twitch_bit

#Kick (kick)

Öğe türleri: gift · birim: kick_kick

#Facebook Live (facebook)

#Instagram Live (instagram)

#Trovo (trovo)

Öğe türleri: spell · birim: trovo_mana, trovo_elixir

Twitch'in varsayılan üç Power-up'ı sabit liste olduğu için eklentiyle toplanmaz; data/platforms/twitch.json içinde static_items olarak tanımlıdır. Kanala özel Power-up'lar katalogda yer almaz, twitch.custom_power_up eventi olarak seçilir.

#Diller

14 dil desteklenir; varsayılan tr. Dil her zaman ?lang= ile seçilir, istek başlıkları okunmaz.

Çözümleme sırası: küçük harfe çevir ve _ yerine - koy → desteklenen kodla başlıyor mu (zh-Hant-TW) → tam kod → covers içinde tam eşleşme (zh-TW) → ilk alt etiket (tr-TR → tr) → ilk alt etiket covers içinde (uk-UA → ru) → tr.

covers yalnızca istemcinin işletim sistemi dilinden otomatik seçim yapması içindir; sistem bir dili başka bir dile çevirmez. Launcher hiçbir eşleşme bulamazsa arayüz için en seçmelidir.

Ad yedekleri: istenen dil → yakın dil (zh-Hant ↔ zh-Hans, pt ↔ es, id → en) → en → tr → öğenin bilinen ilk dili.

#Ortak veri standardı

#Sıralama

sort=default (Launcher sırası): platform sırası → order'ı platformun items_order değerinden küçük sabit eventler → normal öğeler değere göre artan, eşitse ada göre → community öğeleri → kalan sabit eventler. items_order yoksa öğeler bütün eventlerden sonra gelir. Öğe kayıtlarının order alanı bu değeri taşır. TikTok ve YouTube'da susturma/engelleme eventi yoktur (yalnızca message_deleted). q= ile arama yapıldığında community öğeleri ayrıca sona taşınmaz.

#Gruplama

group parametresi düz listeyi iç içe gruplara böler; seviye sırası parametredeki sıradır:

Gruplar platform order ve taksonomi sırasıyla gelir; boş gruplar dönmez. Her en alt grup kendi kayıtlarının tamamını taşır; sayfalama yoktur.

#Düzeltmeler (overrides)

data/overrides/{platform}.json ingest verisinin üstüne okuma sırasında uygulanır ve her zaman son sözü söyler:

{
  "gift": {
    "7934": { "flags": { "community": true } },
    "5655": { "names": { "tr": "Gül" } }
  }
}

flags ve attributes birleştirilir; names dil başına adı değiştirir; diğer alanlar (value, icon) doğrudan değiştirilir.

#Dosya düzeni

platform-events/
├─ API.md · README.md · INGEST.md
├─ index.php                  ← GET (okuma)
├─ ingest.php                 ← POST (Chrome eklentisi, launcher) · GET ?schema=1
├─ config.php                 ← base_url, ingest_token, diller, sınırlar
├─ schema/ingest.schema.json
├─ src/                       ← Http, Lang, Store, Catalog, Ingest
├─ data/                      ← elle yazılır (depoda)
│  ├─ taxonomy.json
│  ├─ platforms/{platform}.json
│  ├─ i18n/{lang}.json
│  └─ overrides/{platform}.json
├─ storage/                   ← ingest yazar (depoya girmez, sunucuda kalıcı)
│  ├─ catalog/{platform}/{item_type}.json
│  ├─ catalog/{platform}/{item_type}.i18n/{lang}.json
│  ├─ submissions/{YYYY-MM-DD}/{submission_id}.json.gz
│  ├─ history/{platform}.{item_type}.jsonl
│  └─ throttle/{sha1}           ← aynı içerik penceresi (30 dk)
├─ media/                     ← yalnızca bizim ürettiğimiz ikonlar
│  ├─ platforms/{color,flat}/{platform}.webp
│  └─ {platform}/events/{native}.webp
└─ tools/tikfinity_import.php ← elle çalıştırılan yedek

Yeni platform eklemek: data/platforms/{id}.json oluşturun, gerekiyorsa data/i18n/*.json dosyalarına event.{id}.{native} anahtarlarını ekleyin ve ikonları media/{id}/events/ altına koyun. Kod değişikliği gerekmez.

#Sunucu

• PHP 8.1+ (json, mbstring; gzip için zlib). Composer gerekmez.
• storage/ web sunucusu kullanıcısı tarafından yazılabilir olmalı ve kod dağıtımında ezilmemelidir.
• nginx önerisi (api.streamember.com kökü api/ klasörü):

location ~ ^/platform-events/(src|data/overrides|storage/(submissions|history)|tools)/ { deny all; }
location = /platform-events/config.php { deny all; }
location ~ ^/platform-events/storage/.*\.lock$ { deny all; }

#Tikfinity yedeği

Eklenti kullanılamadığında TikTok listesi elle alınabilir:

php tools/tikfinity_import.php            # 14 dil
php tools/tikfinity_import.php tr en      # yalnızca bu diller
php tools/tikfinity_import.php --file=kayit.json tr

Araç ingest sözleşmesini kullanır (source.agent: tikfinity-import) ve yalnızca eksikleri tamamlar: yeni hediyeleri ve eksik çevirileri ekler, eklentinin topladığı değer, ikon ve bayrakları ezmez.