Özellikler
Gamification
Kullanıcının ekonomi ve oyunlaştırma durumu: kredi cüzdanı (wallet), envanter
ve avatar itemları, mağaza, claim edilebilir ödüller, streak'ler ve loot box'lar.
Tüm endpointler Bearer ister; yollar
/api/gamification/... ile başlar.
Kavramlar
| Kavram | Açıklama |
|---|---|
| Wallet | Kullanıcının para birimi bakiyesi (ör. Credits). Satın alma/satış bunu değiştirir. |
| Item / Inventory | Kullanıcının sahip olduğu itemlar (envanter). Bazıları avatarda takılabilir (equippable). |
| Equipped avatar | Avatarda aktif olan itemlar. Aynı kategori/slot'ta tek item aktif olur. |
| Store | Aktif kategoriler, rarity'ler ve satın alınabilir itemlardan oluşan katalog. |
| Reward grant | Gameplay'in ürettiği claim edilebilir ödül. Pending iken claim edilir; sonra state'e uygulanır. |
| Streak | Günlük GameSession tamamlama serisi; döngü dolunca ödül üretir. |
| Loot box | Açıldığında item veya currency veren kutu. |
| Mission (görev) | Günlük görevler; bir metrikte hedefe ulaşınca Credits ödülü verir. Her gün İstanbul gece yarısında yenilenir. |
| Achievement | Tier'lı (kademeli) başarımlar. Kullanıcı açtıkça unlock olur; Unity animasyonu sonrası "görüldü" işaretlenir. |
| Feed | Sınıf içindeki public gamification olayları akışı (ör. bir öğrencinin achievement açması). |
| Leaderboard | Sınıf XP sıralaması: AllTime, haftalık (ISO) veya aylık. |
Durumu okuma
- GET /api/gamification/me — wallet, envanter, takılı avatar itemları ve açılmamış loot box'lar.
- GET /api/gamification/streaks/me — streak durumları.
- GET /api/gamification/missions/me —
günün görevleri; ilerleme (
progressValue/targetValue) venextRefreshOnUtc(bir sonraki İstanbul gece yarısı). Liste gösterilecek sırayla gelir. Görevler, liste hiç açılmadan oynansa da o günün ilk oyun olayında atanır ve ilerler. Tamamlanan görevin ödülü, ödül akışıyla (pending → claim) alınır. - GET /api/gamification/classroom — aynı sınıftaki öğrencilerin public avatar görünümü.
- GET /api/gamification/store/catalog — mağaza katalogu + kullanıcının owned/equipped/wallet durumu.
Günlük görevler
Her öğrenciye her gün aynı görevler atanır ve İstanbul gece yarısında (UTC 21:00) yenilenir. İstemci görev ilerletmez; sunucu oyun olaylarından ilerletir, Unity yalnızca GET /api/gamification/missions/me ile okur. Liste API'nin döndürdüğü sırayla gösterilmelidir. Görevler o günün ilk görev okumasında ya da ilk oyun olayında atanır; öğrenci görev ekranını açmadan oynasa da ilerleme kaybolmaz.
| Sıra | missionCode | metricCode | Ne sayılır | Hedef | Zorluk | Ödül |
|---|---|---|---|---|---|---|
| 1 | daily-complete-daily-session-1 | CompleteGameSessions | Günlük setin tamamlanması | 1 | Easy | 12 |
| 2 | daily-perfect-activities-1 | CompletePerfectActivities | Günlük setteki bir aktivitenin wrongAnswerCount = 0 ile bitmesi (mini oyunlar sayılmaz) | 1 | Easy | 3 |
| 3 | daily-complete-daily-session-75-plus | CompleteGameSessionsWithMinAccuracy | Set tamamlandığında toplam doğru / (doğru + yanlış) ≥ %75 (eşik dahil: 16 sorudan 12 doğru sayılır) | 1 | Hard | 25 |
| 4 | daily-play-distinct-mini-games-2 | CompleteDistinctMiniGames | Farklı mini oyunlarda tamamlanan denemeler; başarısız deneme de sayılır, aynı oyun bir kez sayılır | 2 | Easy | 8 |
| 5 | daily-complete-mini-game-levels-1 | CompleteMiniGameLevels | Bir mini oyunda seviye atlama | 1 | Medium | 12 |
- Katalog sunucuda tutulur; görev kodları, metinler ve ödüller değişebilir. Ekranı
sabit listeye değil yanıttaki
displayName,description,targetValue,progressValueverewardCreditAmountalanlarına göre çiz. Görev sayısı 5'ten farklı olabilir. - Yenileme anı
nextRefreshOnUtc'dir; bu anda listeyi yeniden iste. - Tamamlanan görev
RewardGrantedolur verewardGrantIdentifiertaşır. Kredi, ödül akışıyla (pending → claim,sourceType = "MissionCompletion") alınır. - Günlük set bittiğinde artık otomatik kredi ödülü (
GameSessionCompletion) oluşmaz; set kazancı 1. görevden gelir. - Sınıf feed'ine yalnız
Hardgörevlerin tamamlanması düşer.
Ödül akışı (kazan → claim)
Ödüller doğrudan verilmez; önce claim edilebilir bir reward grant olarak birikir (bir gelen kutusu gibi), sonra kullanıcı claim eder.
Bekleyen ödülleri listele
GET /api/gamification/rewards/pending
Ödülü claim et
POST /api/gamification/rewards/{rewardGrantIdentifier}/claim
Currency ise wallet güncellenir, item ise envantere eklenir, loot box ise
somut loot box verilir. Aynı claim tekrar gönderilirse
isIdempotentReplay: true döner ve state ikinci kez değişmez.
Ödül kaynakları (sourceType)
Her reward grant, onu üreten kaynağı sourceType alanında taşır. Unity bir ödülün
nereden geldiğini (ör. streak sandığı mı, görev ödülü mü) bu alandan anlar.
sourceReferenceIdentifier ödülü tetikleyen kaydın ID'sini, grantKey
ise aynı kaynaktan aynı ödülün iki kez verilmesini engelleyen anahtarı verir.
| sourceType | Ne zaman oluşur | rewardKindCode | grantKey | sourceReferenceIdentifier |
|---|---|---|---|---|
Event |
Etkinlik bitince, oyuncunun ilk etkinlik listesinde: koşusunun ulaştığı en yüksek puan eşiğinin her ödülü için bir grant. Ayrıntı: Etkinlikler. | Currency / LootBox |
event-reward-{ödül ID'si} |
Koşunun ID'si (runIdentifier) |
AssignmentCompletion |
Son teslim tarihi 18 Ekim 2026 veya sonrası olan System paragraf ödevinin tüm zorunlu paragrafları tamamlanıp teslim edildiğinde. | LootBox |
assignment-completion-loot-box |
Assignment UniqueIdentifier (GUID) |
DailyStreakCompletion |
Günlük GameSession streak döngüsü tamamlandığında (art arda requiredDays gün; varsayılan 7). Streak bitiminde gelen sandık budur. |
LootBox |
daily-streak-loot-box |
Döngüyü tamamlayan UserGameSession ID'si |
GameSessionCompletion |
Her GameSession tamamlandığında. Güncel ayarda kapalı: set tamamlama kazancı "Günlük seti tamamla" görevinden gelir. | Currency / LootBox |
completion-credits / completion-loot-box |
Tamamlanan UserGameSession ID'si |
XpMilestone |
Toplam XP her eşik katını geçtiğinde (varsayılan her 1000 XP). Tek seferde birden fazla eşik geçilirse her eşik için ayrı grant oluşur. | Currency / LootBox |
general-xp-{milestoneXp}-credits / general-xp-{milestoneXp}-loot-box |
PlayerLevelEvent ID'si |
MissionCompletion |
Bir görev (mission) tamamlandığında. | Currency |
mission-credits |
UserMission ID'si |
TestOps |
Yalnız test ortamında, TestOps "Sandık ver" endpoint'iyle. | LootBox |
testops-loot-box |
TestOps audit kaydı ID'si |
- Streak döngüsünü tamamlayan GameSession bittiğinde sunucu bir
Pendingreward grant oluşturur:sourceType = "DailyStreakCompletion",rewardKindCode = "LootBox",grantKey = "daily-streak-loot-box". Hangi sandığın verileceğilootBox.lootBoxCodealanında gelir (varsayılan yapılandırmadastreak-rare-box, 1 adet). - Grant, GET /api/gamification/rewards/pending listesinde görünür.
Claim edildiğinde yanıtın
lootBoxesdizisi somut loot box'ları (userLootBoxIdentifier) döndürür. Sandık bu ID ile POST /api/gamification/loot-boxes/{userLootBoxIdentifier}/open üzerinden açılır. - Claim edildikten sonra oluşan loot box kaydı kaynak türünü taşımaz. Sandığın streak'ten
geldiğini anlamak için kontrolü claim öncesinde veya claim yanıtındaki
reward.sourceTypeüzerinden yapın. - Bir sonraki tamamlamanın döngüyü bitirip bitirmeyeceği
GET /api/gamification/streaks/me yanıtındaki
wouldNextCompletionCompleteCyclealanından okunur.
"Streak" değil, "DailyStreakCompletion"'dır. Sınıf feed'indeki
StreakMilestone bir feed kaynak türüdür (feed öğesinin
sourceType / feedTypeCode alanı) ve reward grant'te dönmez.
/streaks/me yanıtındaki streakTypeCode = "GameSessionCompletion" ise
streak'in türüdür; reward grant'teki GameSessionCompletion kaynağıyla aynı isimde
olsa da farklı bir alandır.
GameSessionCompletion kapalıdır (set tamamlama
kazancı günlük görevden gelir); XpMilestone yalnız 100 Credits verir (sandık
kodu boş olduğu için loot box grant'i oluşmaz). AssignmentCompletion bir
assignment-common-box, DailyStreakCompletion bir
streak-rare-box hakkı verir. Ödev sandığında Common/Rare/Epic/25 Credits
ağırlıkları 70/20/5/5; streak sandığında Rare/Epic/Legendary/75 Credits ağırlıkları
60/25/5/10'dur. Her ikisi de önce Pending olur. Unity sabit değerlere değil,
sourceType ve rewardKindCode alanlarına göre karar vermelidir.
Mağaza, avatar, satış ve loot box
- POST /api/gamification/store/items/{itemCode}/purchase — katalog itemını Credits ile satın al.
- POST /api/gamification/items/{userItemIdentifier}/equip / .../unequip — avatar itemını tak/çıkar.
- POST /api/gamification/items/{userItemIdentifier}/sell — equipped olmayan bir itemı Credits karşılığı sat.
- POST /api/gamification/loot-boxes/{userLootBoxIdentifier}/open — loot box aç, ödülü envanter/wallet'a uygula.
Achievement, sınıf feed'i ve XP sıralaması
- GET /api/gamification/achievements/me — achievement katalogu + kullanıcının unlock/seen durumu (tier'lı).
- POST /api/gamification/achievements/{userAchievementIdentifier}/seen — kazanılan achievement tier'ını (Unity animasyonu sonrası) görüldü işaretle.
- GET /api/gamification/classroom/feed —
sınıf feed'i. Opsiyonel
limit(varsayılan 20, üst sınır 50). - GET /api/gamification/classroom/leaderboard — sınıf (StudyRoom) XP sıralaması.
- GET /api/gamification/sub-corporation/leaderboard — alt kurum (sub corporation) XP sıralaması. Sınıf sıralamasıyla aynı parametreler ve aynı yanıt şekli; tek fark kapsam. Kapsam: kullanıcının sınıfının bağlı olduğu alt kurumdaki, kullanıcıyla aynı sınıf seviyesindeki (Grade) aktif öğrenciler.
period = AllTime (varsayılan) / Weekly / Monthly.
Weekly için year+week (ISO hafta), Monthly
için year+month; boşsa güncel UTC dönem. limit
varsayılan 50, üst sınır 100. Yanıt, kullanıcı ilk N dışında kalsa bile kendi satırını
currentUserEntry olarak ayrıca döndürür.
AchievementUnlocked, MissionCompleted,
PlayerLevelUp, MiniGameLevelMilestone,
WordMasteryMilestone, StreakMilestone,
AssignmentCompleted, RareLootObtained. Her öğe ayrıca
lokalize render için templateCode + templateArgumentsJson
taşır (eski kayıtlarda null olabilir). MissionCompleted yalnız
Hard zorluktaki görevler için oluşur.
period: AllTime (varsayılan), Weekly veya
Monthly. Weekly için year + week
(ISO hafta), Monthly için year + month
verilir; boşsa güncel UTC dönem kullanılır. limit varsayılan 50, üst
sınır 100. Yanıt, ilk N dışında kalsa bile giriş yapan kullanıcının satırını
(currentUserEntry) ayrıca döndürür.
clientAttemptIdentifier
gönderilir. Aynı işlemi (ağ tekrarında) iki kez uygulamamak içindir; aynı kimlikle
gelen tekrar, önceki sonucu döndürür.
Sabit değerler (enum)
Bu alanlar sabit bir değer kümesinden veya sunucu kataloğundan gelir. Katalog değerleri (lootBoxCode, kategori, rarity, achievement kuralları) yeni katalog kaydıyla genişleyebilir; istemci tanımadığı bir değerde çökmemeli, varsayılan görünüme düşmelidir.
| Alan | Olası değerler |
|---|---|
wallet / ödül currencyCode | Credits (şu an tek para birimi) |
reward rewardKindCode | Currency, Item, LootBox |
reward statusCode | Pending, Claimed, Expired, Revoked |
reward sourceType | AssignmentCompletion, DailyStreakCompletion, GameSessionCompletion, XpMilestone, MissionCompletion, Event, TestOps (ayrıntı: yukarıdaki "Ödül kaynakları" tablosu) |
loot box statusCode | Granted, Opened, Expired, Revoked |
loot box ödülü kind | Item, Currency |
lootBoxCode | streak-rare-box (7 günlük seri sandığı), assignment-common-box (haftalık ödev sandığı), event-silver-box (Gümüş Sandık), event-gold-box (Altın Sandık), event-diamond-box (Elmas Sandık); son üçü etkinlik ödülü |
item itemTypeCode | Wearable, Consumable, Boost, Chest, CurrencyPack, Cosmetic; güncel katalogdaki tüm item'lar Wearable |
item / mağaza categoryCode | Hat, Outfit, Held; üst kategori WearableItems (parentCategoryCode). Envanterde kalan eski, pasif item'larda Hair, Tops, Bottoms, Shoes, Accessories görülebilir |
rarityCode (item, mağaza, achievement tier, loot box ödülü) | Common, Rare, Epic, Legendary |
avatarCode | DefaultAvatar (başlangıç avatarı; katalogdaki tek avatar) |
streak streakTypeCode | GameSessionCompletion |
mission statusCode | Active, Completed, RewardGranted, Expired |
mission difficultyCode | Easy, Medium, Hard |
mission metricCode | CompleteGameSessions, CompleteParagraphs, CorrectAnswers, GainXp, OpenLootBoxes, PurchaseItems, CompleteWordLearningSessions, CorrectWordLearningAnswers, MasterWords, CompleteMiniGameLevels, CompletePerfectActivities, CompleteGameSessionsWithMinAccuracy, CompleteDistinctMiniGames. Güncel katalogda aktif olanlar: CompleteGameSessions, CompletePerfectActivities, CompleteGameSessionsWithMinAccuracy, CompleteDistinctMiniGames, CompleteMiniGameLevels |
achievement achievementTypeCode | ProgressAreaMastery |
achievement tierCode | Bronze, Silver, Gold (rarity eşlemesi: Bronze=Common, Silver=Rare, Gold=Epic) |
achievement ruleCode | Bronze: grade-1-12-own-grade-75; Silver: grade-1-10-plus-one-grade, grade-11-grade-12, grade-12-score-85; Gold: grade-1-10-plus-one-grade-75, grade-11-grade-12-score-85, grade-12-score-95 |
achievement achievementCode / assetCode | Biçim: ProgressArea{progressAreaCode}Mastery; asset Achievement_ProgressArea_{progressAreaCode}; tier asset Achievement_ProgressArea_{progressAreaCode}_{tierCode} |
progressAreaCode | FindingInformation, MainIdea, Inference, VocabularyGrammar, Perspective, Evidence, Comparison, Evaluation |
feed feedTypeCode / sourceType | AchievementUnlocked, MissionCompleted, PlayerLevelUp, MiniGameLevelMilestone, WordMasteryMilestone, StreakMilestone, AssignmentCompleted, RareLootObtained |
feed templateCode | gamification.achievement-unlocked, gamification.mission-completed, gamification.player-level-up, gamification.mini-game-level-milestone, gamification.word-mastery-milestone, gamification.streak-milestone, gamification.assignment-completed, gamification.rare-loot-obtained (eski kayıtlarda null) |
leaderboard periodCode | AllTime, Weekly, Monthly |
level levelTypeCode | General |
Gamification endpointleri
| Endpoint | Ne yapar |
|---|---|
| GET /me | Wallet, envanter, avatar, loot box durumu |
| GET /rewards/pending | Claim bekleyen ödüller |
| POST /rewards/{id}/claim | Ödülü claim et |
| GET /streaks/me | Streak durumu |
| GET /missions/me | Günün görevleri (missions) |
| GET /achievements/me | Achievement katalog + unlock durumu |
| POST /achievements/{id}/seen | Achievement'ı görüldü işaretle |
| GET /classroom | Sınıf avatar görünümü |
| GET /classroom/feed | Sınıf feed'i |
| GET /classroom/leaderboard | Sınıf XP sıralaması |
| GET /sub-corporation/leaderboard | Alt kurum XP sıralaması |
| GET /store/catalog | Mağaza katalogu |
| POST /store/items/{itemCode}/purchase | Mağazadan item satın al |
| POST /items/{id}/equip | Avatar itemı tak |
| POST /items/{id}/unequip | Avatar itemı çıkar |
| POST /items/{id}/sell | Envanter itemını sat |
| POST /loot-boxes/{id}/open | Loot box aç |