Ö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

KavramAçıklama
WalletKullanıcının para birimi bakiyesi (ör. Credits). Satın alma/satış bunu değiştirir.
Item / InventoryKullanıcının sahip olduğu itemlar (envanter). Bazıları avatarda takılabilir (equippable).
Equipped avatarAvatarda aktif olan itemlar. Aynı kategori/slot'ta tek item aktif olur.
StoreAktif kategoriler, rarity'ler ve satın alınabilir itemlardan oluşan katalog.
Reward grantGameplay'in ürettiği claim edilebilir ödül. Pending iken claim edilir; sonra state'e uygulanır.
StreakGünlük GameSession tamamlama serisi; döngü dolunca ödül üretir.
Loot boxAçı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.
AchievementTier'lı (kademeli) başarımlar. Kullanıcı açtıkça unlock olur; Unity animasyonu sonrası "görüldü" işaretlenir.
FeedSınıf içindeki public gamification olayları akışı (ör. bir öğrencinin achievement açması).
LeaderboardSı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) ve nextRefreshOnUtc (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ıramissionCodemetricCodeNe sayılırHedefZorlukÖdül
1daily-complete-daily-session-1CompleteGameSessionsGünlük setin tamamlanması1Easy12
2daily-perfect-activities-1CompletePerfectActivitiesGünlük setteki bir aktivitenin wrongAnswerCount = 0 ile bitmesi (mini oyunlar sayılmaz)1Easy3
3daily-complete-daily-session-75-plusCompleteGameSessionsWithMinAccuracySet tamamlandığında toplam doğru / (doğru + yanlış) ≥ %75 (eşik dahil: 16 sorudan 12 doğru sayılır)1Hard25
4daily-play-distinct-mini-games-2CompleteDistinctMiniGamesFarklı mini oyunlarda tamamlanan denemeler; başarısız deneme de sayılır, aynı oyun bir kez sayılır2Easy8
5daily-complete-mini-game-levels-1CompleteMiniGameLevelsBir mini oyunda seviye atlama1Medium12
Görev ekranı için kurallar
  • Katalog sunucuda tutulur; görev kodları, metinler ve ödüller değişebilir. Ekranı sabit listeye değil yanıttaki displayName, description, targetValue, progressValue ve rewardCreditAmount alanlarına göre çiz. Görev sayısı 5'ten farklı olabilir.
  • Yenileme anı nextRefreshOnUtc'dir; bu anda listeyi yeniden iste.
  • Tamamlanan görev RewardGranted olur ve rewardGrantIdentifier taşı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 Hard gö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.

1

Bekleyen ödülleri listele

GET /api/gamification/rewards/pending

2

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

sourceTypeNe zaman oluşurrewardKindCodegrantKeysourceReferenceIdentifier
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 sandığı: akış ve tanıma
  • Streak döngüsünü tamamlayan GameSession bittiğinde sunucu bir Pending reward grant oluşturur: sourceType = "DailyStreakCompletion", rewardKindCode = "LootBox", grantKey = "daily-streak-loot-box". Hangi sandığın verileceği lootBox.lootBoxCode alanında gelir (varsayılan yapılandırmada streak-rare-box, 1 adet).
  • Grant, GET /api/gamification/rewards/pending listesinde görünür. Claim edildiğinde yanıtın lootBoxes dizisi 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 wouldNextCompletionCompleteCycle alanından okunur.
Karıştırılmaması gerekenler Değer "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.
Yapılandırmaya bağlı ödüller Gün sayısı, tutarlar ve sandık kodları sunucu yapılandırmasından gelir; ortama göre değişebilir. Varsayılan yapılandırmada 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.
Leaderboard parametreleri (her iki sıralama için ortak) 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.
Feed türleri (feedTypeCode) 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.
Leaderboard parametreleri 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.
Idempotency: ClientAttemptIdentifier Satın alma, satış ve loot box açma isteklerinde 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.

AlanOlası değerler
wallet / ödül currencyCodeCredits (şu an tek para birimi)
reward rewardKindCodeCurrency, Item, LootBox
reward statusCodePending, Claimed, Expired, Revoked
reward sourceTypeAssignmentCompletion, DailyStreakCompletion, GameSessionCompletion, XpMilestone, MissionCompletion, Event, TestOps (ayrıntı: yukarıdaki "Ödül kaynakları" tablosu)
loot box statusCodeGranted, Opened, Expired, Revoked
loot box ödülü kindItem, Currency
lootBoxCodestreak-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 itemTypeCodeWearable, Consumable, Boost, Chest, CurrencyPack, Cosmetic; güncel katalogdaki tüm item'lar Wearable
item / mağaza categoryCodeHat, 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
avatarCodeDefaultAvatar (başlangıç avatarı; katalogdaki tek avatar)
streak streakTypeCodeGameSessionCompletion
mission statusCodeActive, Completed, RewardGranted, Expired
mission difficultyCodeEasy, Medium, Hard
mission metricCodeCompleteGameSessions, CompleteParagraphs, CorrectAnswers, GainXp, OpenLootBoxes, PurchaseItems, CompleteWordLearningSessions, CorrectWordLearningAnswers, MasterWords, CompleteMiniGameLevels, CompletePerfectActivities, CompleteGameSessionsWithMinAccuracy, CompleteDistinctMiniGames. Güncel katalogda aktif olanlar: CompleteGameSessions, CompletePerfectActivities, CompleteGameSessionsWithMinAccuracy, CompleteDistinctMiniGames, CompleteMiniGameLevels
achievement achievementTypeCodeProgressAreaMastery
achievement tierCodeBronze, Silver, Gold (rarity eşlemesi: Bronze=Common, Silver=Rare, Gold=Epic)
achievement ruleCodeBronze: 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 / assetCodeBiçim: ProgressArea{progressAreaCode}Mastery; asset Achievement_ProgressArea_{progressAreaCode}; tier asset Achievement_ProgressArea_{progressAreaCode}_{tierCode}
progressAreaCodeFindingInformation, MainIdea, Inference, VocabularyGrammar, Perspective, Evidence, Comparison, Evaluation
feed feedTypeCode / sourceTypeAchievementUnlocked, MissionCompleted, PlayerLevelUp, MiniGameLevelMilestone, WordMasteryMilestone, StreakMilestone, AssignmentCompleted, RareLootObtained
feed templateCodegamification.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 periodCodeAllTime, Weekly, Monthly
level levelTypeCodeGeneral

Gamification endpointleri

EndpointNe yapar
GET /meWallet, envanter, avatar, loot box durumu
GET /rewards/pendingClaim bekleyen ödüller
POST /rewards/{id}/claimÖdülü claim et
GET /streaks/meStreak durumu
GET /missions/meGünün görevleri (missions)
GET /achievements/meAchievement katalog + unlock durumu
POST /achievements/{id}/seenAchievement'ı görüldü işaretle
GET /classroomSınıf avatar görünümü
GET /classroom/feedSınıf feed'i
GET /classroom/leaderboardSınıf XP sıralaması
GET /sub-corporation/leaderboardAlt kurum XP sıralaması
GET /store/catalogMağaza katalogu
POST /store/items/{itemCode}/purchaseMağazadan item satın al
POST /items/{id}/equipAvatar itemı tak
POST /items/{id}/unequipAvatar itemı çıkar
POST /items/{id}/sellEnvanter itemını sat
POST /loot-boxes/{id}/openLoot box aç
Alan bazlı tam şema Her endpoint'in request/response alanları İnteraktif API Referansı'nda (Gamification bölümü) yer alır.