Özellikler

Geri Bildirim (Feedback)

Öğrenci uygulama içinden konu, yıldız puanı, mesaj ve isteğe bağlı ekran görüntüsü/log dosyası gönderir. Kayıt ekip tarafından BackOffice'te incelenir. Tüm endpointler Bearer ister; yollar /api/feedback ile başlar.

Tek zorunlu alan: konu Konu (topicCode ya da customTopic) dışındaki her alan isteğe bağlıdır. Göndermemek, boş göndermek ya da yalnız boşluk göndermek aynı şeydir: alan "yok" sayılır. API bilmediği form alanlarını yok sayar; istemciye yeni alan eklemek isteği bozmaz.

Akış

1

Konuları oku

GET /api/feedback/topics

Aktif konuları gösterim sırasıyla döner. Konu listesi ekip tarafından BackOffice'ten değiştirilebilir; istemci listeyi sabit kodlamaz, bu endpoint'ten çizer. Listede her zaman tek bir isCustom: true konu vardır: kullanıcı bu konuyu seçerse konuyu kendisi yazar.

Cevap (data)
[
  { "code": "bug",        "displayName": "Hata / sorun",                  "isCustom": false },
  { "code": "content",    "displayName": "Okuma metni veya soru",         "isCustom": false },
  { "code": "game",       "displayName": "Oyun ve günlük görev",          "isCustom": false },
  { "code": "suggestion", "displayName": "Öneri",                         "isCustom": false },
  { "code": "account",    "displayName": "Hesap ve giriş",                "isCustom": false },
  { "code": "custom",     "displayName": "Diğer (konuyu kendim yazayım)", "isCustom": true }
]

Yukarıdaki liste başlangıç konularıdır; güncel liste her zaman endpoint'ten gelir.

2

Geri bildirimi gönder

POST /api/feedback

Gövde JSON değil, formdur: dosya varsa multipart/form-data, dosya yoksa multipart/form-data ya da application/x-www-form-urlencoded. Unity'de WWWForm ikisini de otomatik seçer. JSON gövde UnsupportedContentType ile reddedilir.

Form alanları

Tüm değerler metin olarak gönderilir. Alan adları büyük/küçük harf duyarsızdır.

AlanZorunluEn fazlaKural
topicCodeEvet*200Konu kodu (GET /api/feedback/topics). Büyük/küçük harf duyarsız. Bkz. konu kuralları.
customTopicEvet*200Kullanıcının yazdığı konu. Yalnız custom konuda saklanır.
ratingHayır–Yıldız 1-5. 0, boş ya da gönderilmemiş = puan verilmedi. 4.0 kabul edilir; 2.5, 7, abc → InvalidRating.
messageHayır4000Kullanıcının mesajı. Aşarsa MessageTooLong.
clientFeedbackIdentifierHayır (önerilir)128Gönderim başına istemcinin ürettiği tekil kimlik (ör. GUID). Bkz. tekrar deneme.
appVersionHayır64Uygulama sürümü (Application.version).
platformHayır64Ör. Android, IPhonePlayer.
osVersionHayır128İşletim sistemi (SystemInfo.operatingSystem).
deviceModelHayır128Cihaz modeli (SystemInfo.deviceModel).
screenContextHayır128Gönderimin yapıldığı ekran/sahne.
metadataHayır8192 baytEk bilgiler için JSON nesnesi (metin olarak, ör. {"scene":"Island","fps":58}). Dizi, düz değer, bozuk JSON ya da 8192 bayt (UTF-8) üstü → InvalidMetadata.
filesHayır3 dosyaEk dosyalar; aynı files adı tekrarlanarak birden çok dosya eklenir. Bkz. dosyalar.

* topicCode ve customTopic'ten en az biri dolu olmalı; ikisi de boşsa TopicRequired.

Uzun değer kırpılmaz, reddedilir Sınırı aşan alan FieldTooLong (mesajda hangi alan olduğu yazar) ya da MessageTooLong döner. Cihaz bilgisi gibi alanları göndermeden önce istemcide sınıra kırp.

Konu kuralları

GönderilenKaydedilen konuKaydedilen özel konu metni
topicCode=bug (hazır, aktif konu)bugyok (customTopic gönderilse de yok sayılır)
topicCode=custom + customTopic=Ses gelmiyorcustomSes gelmiyor
topicCode=custom, customTopic boşcustomyok
topicCode boş + customTopic=Ses gelmiyorcustomSes gelmiyor
Bilinmeyen ya da pasifleştirilmiş kod, ör. topicCode=musiccustomcustomTopic doluysa o, değilse music
İkisi de boşTopicRequired (kayıt yok)

Böylece eski bir istemci sürümü kaldırılmış bir konuyu gönderse bile geri bildirim kaybolmaz.

Dosyalar

KuralDeğer
AdetEn fazla 3 (aşarsa TooManyAttachments)
BoyutDosya başına 10 MB, toplam 25 MB (aşarsa AttachmentTooLarge); boş dosya EmptyAttachment
TürlerPNG, JPEG, WEBP (ekran görüntüsü) ve UTF-8 metin/JSON (log). Diğerleri UnsupportedAttachmentType
Tür tespitiDosya adı ve gönderilen content-type'a bakılmaz; dosyanın içeriğinden belirlenir
Hepsi ya da hiçbiriDosyalardan biri geçersizse istek bütünüyle reddedilir, hiçbir şey kaydedilmez
İstek gövdesi üst sınırı: 28 MB 25 MB'lık ek sınırı envelope içinde (AttachmentTooLarge) döner. Ancak gövdenin tamamı 28 MB'ı aşarsa istek API koduna ulaşmadan reddedilir ve envelope dışında HTTP 400 gelir. Dosya boyutlarını göndermeden önce istemcide kontrol et.

Cevap

Başarılı cevap (data)
{
  "feedbackIdentifier": "572a0db8-6d18-4478-be8c-927fb8af3522",
  "createdOnUtc": "2026-10-08T19:04:32.330606Z",
  "attachmentCount": 2,
  "isIdempotentReplay": false
}

Tekrar deneme (idempotency)

Kullanıcının her "Gönder" eylemi için bir kez clientFeedbackIdentifier üret ve o gönderimin tüm tekrar denemelerinde aynı değeri kullan. Aynı kullanıcı aynı değerle tekrar gönderirse yeni kayıt açılmaz; ilk kayıt isIdempotentReplay: true ile döner (bu istekteki dosyalar kaydedilmez). Böylece ağ kopması sonrası tekrar deneme çift kayıt üretmez. Tekrar deneme hız sınırına takılmaz.

Hata kodları

Hepsi HTTP 200 ve isSuccess: false ile gelir (bkz. Cevaplar & Hatalar).

statusCodeNe zamanİstemci ne yapmalı
TopicRequiredtopicCode ve customTopic ikisi de boşKullanıcıdan konu seçmesini iste
InvalidRatingPuan 1-5 değil (0 hariç) ya da sayı değilİstemci hatası; puanı düzelt
MessageTooLongMesaj 4000 karakteri aşıyorMetin kutusunu 4000 ile sınırla
FieldTooLongBaşka bir metin alanı sınırını aşıyor (mesajda alan adı yazar)Alanı istemcide kırp
InvalidMetadatametadata JSON nesnesi değil ya da 8192 bayt üstüİstemci hatası; metadata'yı düzelt ya da gönderme
TooManyAttachments3'ten fazla dosyaEn fazla 3 dosya ekle
AttachmentTooLargeDosya 10 MB ya da toplam 25 MB üstüGörüntüyü küçült (ör. JPEG) ya da dosyayı çıkar
EmptyAttachment0 baytlık dosyaBoş dosyayı ekleme
UnsupportedAttachmentTypeİçerik PNG/JPEG/WEBP/UTF-8 metin değilDesteklenen türde gönder
UnsupportedContentTypeGövde form değil (ör. JSON)WWWForm / multipart kullan
FeedbackRateLimitedAynı kullanıcı 10 dakikada 5'ten fazla gönderdiKullanıcıya "biraz sonra tekrar dene" göster; otomatik tekrar deneme yapma
AttachmentStorageFailedDosya depolamaya yazılamadı (geçici sunucu sorunu)Aynı clientFeedbackIdentifier ile biraz sonra tekrar dene
UserNotFoundKullanıcı bulunamadı ya da pasifOturumu kapatıp yeniden giriş iste
UnauthorizedToken geçerli ama kullanıcı kimliği okunamadıYeniden giriş yap
FeedbackTopicsNotConfiguredSunucuda custom konu tanımlı değil (yapılandırma hatası)Hata göster; ekibe bildir

Token hiç yoksa ya da süresi dolmuşsa cevap HTTP 401'dir (envelope yok).

Unity örneği

Modeller (JsonUtility)
[Serializable] public class FeedbackTopic { public string code; public string displayName; public bool isCustom; }
[Serializable] public class FeedbackTopicsResponse { public bool isSuccess; public string statusCode; public string message; public FeedbackTopic[] data; }

[Serializable] public class SubmitFeedbackData { public string feedbackIdentifier; public string createdOnUtc; public int attachmentCount; public bool isIdempotentReplay; }
[Serializable] public class SubmitFeedbackResponse { public bool isSuccess; public string statusCode; public string message; public SubmitFeedbackData data; }
Konuları yükle
IEnumerator LoadTopics(string accessToken, Action<FeedbackTopic[]> onLoaded)
{
    using var req = UnityWebRequest.Get("https://api.readhaven.co/api/feedback/topics");
    req.SetRequestHeader("Authorization", "Bearer " + accessToken);
    yield return req.SendWebRequest();
    if (req.result != UnityWebRequest.Result.Success) yield break; // ağ hatası ya da 401

    var res = JsonUtility.FromJson<FeedbackTopicsResponse>(req.downloadHandler.text);
    if (res.isSuccess) onLoaded(res.data);
}
Ekran görüntüsü al (isteğe bağlı)
IEnumerator CaptureScreenshot(Action<byte[]> onCaptured)
{
    yield return new WaitForEndOfFrame();
    var texture = ScreenCapture.CaptureScreenshotAsTexture();
    var jpg = texture.EncodeToJPG(75); // PNG de olur; JPEG daha küçük
    Destroy(texture);
    onCaptured(jpg);
}
Gönder
static string Cap(string value, int max) =>
    string.IsNullOrEmpty(value) || value.Length <= max ? value : value.Substring(0, max);

// clientFeedbackIdentifier: kullanıcı "Gönder"e bastığında BİR KEZ üret
// (Guid.NewGuid().ToString()), tekrar denemelerde aynısını kullan.
IEnumerator SubmitFeedback(
    string accessToken,
    string clientFeedbackIdentifier,
    string topicCode,        // seçilen konunun code'u
    string customTopic,      // yalnız isCustom konuda, yoksa null
    int rating,              // 1-5; 0 = puan yok
    string message,
    byte[] screenshotJpg,    // yoksa null
    string logText,          // yoksa null
    Action<SubmitFeedbackResponse> onDone)
{
    var form = new WWWForm();
    form.AddField("clientFeedbackIdentifier", clientFeedbackIdentifier);
    if (!string.IsNullOrEmpty(topicCode)) form.AddField("topicCode", topicCode);
    if (!string.IsNullOrEmpty(customTopic)) form.AddField("customTopic", Cap(customTopic, 200));
    form.AddField("rating", rating);
    if (!string.IsNullOrEmpty(message)) form.AddField("message", Cap(message, 4000));
    form.AddField("appVersion", Cap(Application.version, 64));
    form.AddField("platform", Cap(Application.platform.ToString(), 64));
    form.AddField("osVersion", Cap(SystemInfo.operatingSystem, 128));
    form.AddField("deviceModel", Cap(SystemInfo.deviceModel, 128));
    form.AddField("screenContext", Cap(SceneManager.GetActiveScene().name, 128));

    if (screenshotJpg != null)
        form.AddBinaryData("files", screenshotJpg, "screenshot.jpg", "image/jpeg");
    if (!string.IsNullOrEmpty(logText))
        form.AddBinaryData("files", Encoding.UTF8.GetBytes(logText), "log.txt", "text/plain");

    using var req = UnityWebRequest.Post("https://api.readhaven.co/api/feedback", form);
    req.SetRequestHeader("Authorization", "Bearer " + accessToken);
    yield return req.SendWebRequest();

    if (req.result == UnityWebRequest.Result.ConnectionError)
    {
        // Ağ hatası: aynı clientFeedbackIdentifier ile tekrar denenebilir.
        yield break;
    }

    var res = JsonUtility.FromJson<SubmitFeedbackResponse>(req.downloadHandler.text);
    onDone(res); // res.isSuccess false ise res.statusCode'a göre davran (tabloya bak)
}
Kendi verilerini metadata'ya koy Ek alan gerekirse yeni form alanı yerine metadata kullan: form.AddField("metadata", JsonUtility.ToJson(myInfo)); (JsonUtility.ToJson nesne üretir; en fazla 8192 bayt).

Tarayıcıdan denemek (Execute)

  1. İnteraktif Referans'ta Auth → Login → Test Request ile giriş yap ve dönen accessToken'ı kopyala.
  2. Feedback → Geri bildirim konuları → Test Request: Authentication bölümündeki Bearer Token alanına token'ı yapıştır → Send. Konu listesi gelir. Token bir kez girilir, diğer isteklerde de kullanılır.
  3. Feedback → Geri bildirim gönder → Test Request: Request Body → Multipart Form. topicCode satırının Value'suna ör. bug yaz; istersen rating, message, clientFeedbackIdentifier doldur; files satırında Select File ile bir PNG seç → Send. Boş bırakılan satırlar gönderilmemiş sayılır.
  4. Aynı clientFeedbackIdentifier ile ikinci kez Send: aynı feedbackIdentifier ve isIdempotentReplay: true gelir.
  5. Hata örnekleri: topicCode ve customTopic'i boşaltınca TopicRequired, rating'e 7 yazınca InvalidRating gelir.
Gerçek kayıt oluşur Execute ile gönderilen geri bildirimler canlı veritabanına yazılır ve ekibin BackOffice listesinde görünür. Denemeleri test kullanıcısıyla yap; hız sınırı (10 dakikada 5) burada da geçerlidir.
Alan bazlı tam şema Request/response alanlarının tamamı İnteraktif API Referansı'nda (Feedback bölümü) yer alır.