Ö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

KavramAçıklama
EtkinlikBaş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ğiKoş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 EventNotFound döner.
  • Özellik sunucuda kapalıysa (Events:IsEnabled=false) liste boş gelir. Liste boşken etkinlik butonu gizlenir.

Akış

1

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 yoksa null; varsa rank, points, scopeCode.
  • reward: ödül yoksa null; bitmiş etkinlikte Pending (claim bekleyen var) ya da Claimed (hepsi alındı) ve rewardGrantIdentifiers.
  • rewardThresholds: eşikler puana göre artan; her ödül ödül kaydındaki şekilde (currency ya da lootBox).
2

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).

3

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.

4

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.

5

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.

6

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.

7

Ö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.

KuralDeğer
Doğru cevap80 puan
Hız bonusuEn ç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 bonusuEn 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.
runScoreHer 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şu10 × 80 + 10 × 42 + 10 × 14 = 1360

Koşu kuralları

  • Tek koşu: sayılan bir koşu varken yeni koşu NoAttemptsLeft alı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 next ve cevap RunFinished alır; istemci finish çağırıp sonucu gösterir.
  • Güvenli tekrar: next, cevap ve finish tekrar gönderilebilir. Aynı soruya ikinci cevap ilk sonucu, tüm alanlar aynı olarak döndürür.
  • Kimlikler: eventIdentifier, runIdentifier, questionIdentifier ve optionIdentifier GUID'dir. A–D etiketleri seçeneğin sırasından çizilir.

Etkinlik sandıkları

lootBoxCodeAdİçerik
event-silver-boxGümüş SandıkCommon %60, Rare %30, Epic %5, %5 olasılıkla 50 kredi
event-gold-boxAltın SandıkRare %60, Epic %25, Legendary %5, %10 olasılıkla 75 kredi
event-diamond-boxElmas SandıkRare %40, Epic %40, Legendary %15, %5 olasılıkla 150 kredi
Tarihler Etkinlik yanıtlarındaki tüm zamanlar UTC'dir ve Z ekiyle gelir (ör. "2026-10-31T21:00:00Z"). Yerel saate çevirme istemcidedir.

Hata kodları

statusCodeNeredeİstemci ne yapar
EventNotFoundtüm etkinlik route'larıEtkinlik yok, yayında değil ya da oyuncu hedef kitlede değil.
EventNotActivebaşlatEtkinlik başlamadı ya da bitti.
NoAttemptsLeftbaşlatOyuncunun sayılan koşusu var.
RunFinishednext, cevapfinish çağırıp sonucu göster.
RunNotFoundnext, cevap, finishKoşu bu oyuncuya ait değil ya da yerine yenisi açıldı.
QuestionNotServedcevapSoru bu koşuda servis edilmedi; "gönderilemedi" + tekrar dene.
InvalidOptioncevapSeçenek bu soruya ait değil; "gönderilemedi" + tekrar dene.
NoMoreQuestionsnextSon sorudan sonra; istemci çağırmaz.
EventNotPlayablebaşlatEtkinliğ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 Smoke klasörü tüm akışı Collection Runner ile doğrular.
Alan bazlı tam şema Request/response alanlarının tamamı İnteraktif API Referansı'nda (Events bölümü) yer alır.