Özellikler
Etkinlikler ve Bilgi Yarışması (Events)
Süreli etkinlikler. İlk tür bilgi yarışması (Trivia): oyuncu etkinlik başına
tek koşu oynar, sorular tek tek gelir, süreyi ve puanı sunucu hesaplar.
Koşunun puanı sınıf ya da okul içinde sıralanır; etkinlik bitince koşunun ulaştığı
en yüksek puan eşiğinin ödülleri verilir. Tüm endpointler
Bearer ister; yollar /api/events/... ile başlar.
Kavramlar
| Kavram | Açıklama |
|---|---|
| Etkinlik | Başlangıç ve bitişi olan yarışma. Aktif: startsAt <= şimdi < endsAt. |
| Koşu (run) | Oyuncunun bir etkinlikteki oyunu. Hiçbir zaman devam ettirilmez. |
| Sayılan koşu | İlk cevabı alan ya da finish ile bırakılan koşu. Oyuncunun tek hakkını harcar. |
| Puan eşiği | Koşunun ulaşması gereken puan. Eşikler üst üste eklenmez; yalnız ulaşılan en yüksek eşiğin ödülleri kazanılır. |
Kapsam (scopeCode) | Classroom: sınıf. School: aynı okul ve aynı sınıf seviyesi. Etkinlik başına sunucu seçer. |
Kim görür
- Her etkinliğin bir sınıf seviyesi aralığı ve kurum filtresi vardır (tüm kurumlar ya da seçilen kurum/alt kurumlar).
- Bireysel kayıtlı öğrenciler etkinlik görmez.
- Hedef kitle dışındaki oyuncu için liste boş gelir; diğer route'lar
EventNotFounddöner. - Özellik sunucuda kapalıysa (
Events:IsEnabled=false) liste boş gelir. Liste boşken etkinlik butonu gizlenir.
Akış
Etkinlikleri listele
GET /api/events
Aktif ve yaklaşan etkinlikler, bitişinden sonraki 7 gün içindeki bitmiş etkinlikler ve
bekleyen ödülü olan bitmiş etkinlikler (süre sınırı olmadan) döner. Geri sayımlar
telefonun saatine değil serverTime'a göre çalışır.
attemptsLeft: sayılan koşu yoksa 1, varsa 0 (günlük yenilenmez).standing: bitmiş koşu yoksanull; varsarank,points,scopeCode.reward: ödül yoksanull; bitmiş etkinliktePending(claim bekleyen var) ya daClaimed(hepsi alındı) verewardGrantIdentifiers.rewardThresholds: eşikler puana göre artan; her ödül ödül kaydındaki şekilde (currencyya dalootBox).
Koşuyu başlat
POST /api/events/{eventIdentifier}/runs gövde: {}
Koşu açılır ve ilk soru doğru cevabı olmadan gelir; sorunun süresi bu yanıt
gönderilirken başlar. attemptsLeft her zaman 0'dır (bu koşu sayıldığında kalan hak).
Cevap gönder
POST /api/events/{eventIdentifier}/runs/{runIdentifier}/answers
İstek gövdesi{
"questionIdentifier": "<sorunun ID'si>",
"optionIdentifier": "<seçeneğin ID'si; süre dolduysa null>",
"elapsedMilliseconds": 2300
}
Yanıt: isCorrect, correctOptionIdentifier (yanlışta ve zaman aşımında da gelir),
points (bu sorunun puanı, hız bonusu dahil), speedBonus, streak,
runScore ve toplamın kırılımı runCorrectPoints, runSpeedBonus,
runStreakBonus, longestStreak.
Sıradaki soru
POST /api/events/{eventIdentifier}/runs/{runIdentifier}/next gövde: {}
Oyuncu sonucu okuyup devam ettiğinde çağrılır; sonucu okuma süresi soru süresine sayılmaz.
Mevcut soru cevaplanmadan tekrar çağrılırsa aynı soru döner ve süresi ilk servisten akmaya
devam eder. Son sorudan sonra çağrılmaz; finish çağrılır.
Koşuyu bitir
POST /api/events/{eventIdentifier}/runs/{runIdentifier}/finish gövde: {}
Son sorudan sonra, oyuncu çıkış butonuyla ayrıldığında ve RunFinished sonrası çağrılır.
Cevaplanmayan sorular puan getirmez. Tekrar çağrılabilir; sunucu koşuyu kendisi bitirdiyse de
sonucu döner. Yanıt: runScore (= correctPoints + speedBonus + streakBonus),
correctCount, questionCount, longestStreak, bestScore
(tek koşu olduğu için runScore ile aynı), rank, scopeCode.
Sıralama
GET /api/events/{eventIdentifier}/leaderboard
Yalnız bitmiş koşular, puana göre; eşit puanda önce bitiren önde, iki oyuncu aynı sırayı paylaşmaz.
Sınıf kapsamında tüm sınıf, okul kapsamında ilk 50 döner. Satırlar sınıf sıralamasıyla aynı
şekildedir (scoreXp yerine score; avatar ve takılı itemlar dahil).
currentUserEntry oyuncunun kendi satırıdır; bitmiş koşusu yoksa null.
Ödülleri al
Etkinlik bitince, oyuncunun bitişten sonraki ilk listesinde ödüller ödül kaydına
sourceType = "Event" ile Pending olarak yazılır; aynı ID'ler etkinliğin
reward.rewardGrantIdentifiers alanında gelir. Her biri mevcut
POST /api/gamification/rewards/{id}/claim ile alınır.
Puanlama
Değerler etkinlik başına sunucuda tutulur; aşağıdakiler ilk etkinliğin değerleridir.
| Kural | Değer |
|---|---|
| Doğru cevap | 80 puan |
| Hız bonusu | En çok 42. Süreyi sunucu ölçer (soru gönderildiğinden cevap geldiği ana); 1 sn ağ payı düşülür, kalan süreye göre 42'den 0'a doğrusal azalır. Telefonun elapsedMilliseconds değeri yalnız loglanır. |
| Seri bonusu | En uzun doğru serisi en az 3 olunca seri başına cevap × 14 (ör. 4'lü seri = 56). |
| Zaman aşımı | optionIdentifier = null ya da cevap süre + 3 sn sonra gelirse 0 puan, seri sıfırlanır. |
runScore | Her yanıtta seri bonusu dahil o ana kadarki toplam. Hiç azalmaz; serinin 3. doğrusunda +42, sonraki her doğruda +14 ek artar. Son cevaptaki değer finish'teki ile aynıdır. |
| Mükemmel koşu | 10 × 80 + 10 × 42 + 10 × 14 = 1360 |
Koşu kuralları
- Tek koşu: sayılan bir koşu varken yeni koşu
NoAttemptsLeftalır. - Sayılmayan koşu: başlatma yanıtı kaybolduysa ya da uygulama ilk soruda kapandıysa koşu sayılmaz; yeni koşu açılır ve aynı ilk soru gelir. Soru sırası her koşuda aynıdır.
- Devam yok: 30 dakika istemciden istek gelmezse ya da etkinlik biterse sunucu koşuyu cevaplananlarla bitirir. Bu koşuya
nextve cevapRunFinishedalır; istemcifinishçağırıp sonucu gösterir. - Güvenli tekrar:
next, cevap vefinishtekrar gönderilebilir. Aynı soruya ikinci cevap ilk sonucu, tüm alanlar aynı olarak döndürür. - Kimlikler:
eventIdentifier,runIdentifier,questionIdentifierveoptionIdentifierGUID'dir. A–D etiketleri seçeneğin sırasından çizilir.
Etkinlik sandıkları
| lootBoxCode | Ad | İçerik |
|---|---|---|
event-silver-box | Gümüş Sandık | Common %60, Rare %30, Epic %5, %5 olasılıkla 50 kredi |
event-gold-box | Altın Sandık | Rare %60, Epic %25, Legendary %5, %10 olasılıkla 75 kredi |
event-diamond-box | Elmas Sandık | Rare %40, Epic %40, Legendary %15, %5 olasılıkla 150 kredi |
Z ekiyle gelir
(ör. "2026-10-31T21:00:00Z"). Yerel saate çevirme istemcidedir.
Hata kodları
| statusCode | Nerede | İstemci ne yapar |
|---|---|---|
EventNotFound | tüm etkinlik route'ları | Etkinlik yok, yayında değil ya da oyuncu hedef kitlede değil. |
EventNotActive | başlat | Etkinlik başlamadı ya da bitti. |
NoAttemptsLeft | başlat | Oyuncunun sayılan koşusu var. |
RunFinished | next, cevap | finish çağırıp sonucu göster. |
RunNotFound | next, cevap, finish | Koşu bu oyuncuya ait değil ya da yerine yenisi açıldı. |
QuestionNotServed | cevap | Soru bu koşuda servis edilmedi; "gönderilemedi" + tekrar dene. |
InvalidOption | cevap | Seçenek bu soruya ait değil; "gönderilemedi" + tekrar dene. |
NoMoreQuestions | next | Son sorudan sonra; istemci çağırmaz. |
EventNotPlayable | başlat | Etkinliğin içeriği eksik; "başlatılamadı". |
Test etme
- İlk etkinlik (
E6B01474-4066-4DB4-B0D5-3221B363E550) yalnız test okullarına açıktır:TEST-SUB,TEST-SUBCORP,TEST-SUBCORP-2. - TestOps ile bir öğrencinin koşusu sıfırlanabilir ve test etkinliğinin zaman aralığı değiştirilebilir (bitişi geçmişe çekmek ödülleri sınar). Bkz. TestOps.
- Postman koleksiyonundaki
Automation Events Trivia Smokeklasörü tüm akışı Collection Runner ile doğrular.