Ö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.
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ış
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.
[
{ "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.
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.
| Alan | Zorunlu | En fazla | Kural |
|---|---|---|---|
topicCode | Evet* | 200 | Konu kodu (GET /api/feedback/topics). Büyük/küçük harf duyarsız. Bkz. konu kuralları. |
customTopic | Evet* | 200 | Kullanıcının yazdığı konu. Yalnız custom konuda saklanır. |
rating | Hayır | – | Yıldız 1-5. 0, boş ya da gönderilmemiş = puan verilmedi. 4.0 kabul edilir; 2.5, 7, abc → InvalidRating. |
message | Hayır | 4000 | Kullanıcının mesajı. Aşarsa MessageTooLong. |
clientFeedbackIdentifier | Hayır (önerilir) | 128 | Gönderim başına istemcinin ürettiği tekil kimlik (ör. GUID). Bkz. tekrar deneme. |
appVersion | Hayır | 64 | Uygulama sürümü (Application.version). |
platform | Hayır | 64 | Ör. Android, IPhonePlayer. |
osVersion | Hayır | 128 | İşletim sistemi (SystemInfo.operatingSystem). |
deviceModel | Hayır | 128 | Cihaz modeli (SystemInfo.deviceModel). |
screenContext | Hayır | 128 | Gönderimin yapıldığı ekran/sahne. |
metadata | Hayır | 8192 bayt | Ek 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. |
files | Hayır | 3 dosya | Ek 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.
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önderilen | Kaydedilen konu | Kaydedilen özel konu metni |
|---|---|---|
topicCode=bug (hazır, aktif konu) | bug | yok (customTopic gönderilse de yok sayılır) |
topicCode=custom + customTopic=Ses gelmiyor | custom | Ses gelmiyor |
topicCode=custom, customTopic boş | custom | yok |
topicCode boş + customTopic=Ses gelmiyor | custom | Ses gelmiyor |
Bilinmeyen ya da pasifleştirilmiş kod, ör. topicCode=music | custom | customTopic 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
| Kural | Değer |
|---|---|
| Adet | En fazla 3 (aşarsa TooManyAttachments) |
| Boyut | Dosya başına 10 MB, toplam 25 MB (aşarsa AttachmentTooLarge); boş dosya EmptyAttachment |
| Türler | PNG, JPEG, WEBP (ekran görüntüsü) ve UTF-8 metin/JSON (log). Diğerleri UnsupportedAttachmentType |
| Tür tespiti | Dosya adı ve gönderilen content-type'a bakılmaz; dosyanın içeriğinden belirlenir |
| Hepsi ya da hiçbiri | Dosyalardan biri geçersizse istek bütünüyle reddedilir, hiçbir şey kaydedilmez |
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).
| statusCode | Ne zaman | İstemci ne yapmalı |
|---|---|---|
TopicRequired | topicCode ve customTopic ikisi de boş | Kullanıcıdan konu seçmesini iste |
InvalidRating | Puan 1-5 değil (0 hariç) ya da sayı değil | İstemci hatası; puanı düzelt |
MessageTooLong | Mesaj 4000 karakteri aşıyor | Metin kutusunu 4000 ile sınırla |
FieldTooLong | Başka bir metin alanı sınırını aşıyor (mesajda alan adı yazar) | Alanı istemcide kırp |
InvalidMetadata | metadata JSON nesnesi değil ya da 8192 bayt üstü | İstemci hatası; metadata'yı düzelt ya da gönderme |
TooManyAttachments | 3'ten fazla dosya | En fazla 3 dosya ekle |
AttachmentTooLarge | Dosya 10 MB ya da toplam 25 MB üstü | Görüntüyü küçült (ör. JPEG) ya da dosyayı çıkar |
EmptyAttachment | 0 baytlık dosya | Boş dosyayı ekleme |
UnsupportedAttachmentType | İçerik PNG/JPEG/WEBP/UTF-8 metin değil | Desteklenen türde gönder |
UnsupportedContentType | Gövde form değil (ör. JSON) | WWWForm / multipart kullan |
FeedbackRateLimited | Aynı kullanıcı 10 dakikada 5'ten fazla gönderdi | Kullanıcıya "biraz sonra tekrar dene" göster; otomatik tekrar deneme yapma |
AttachmentStorageFailed | Dosya depolamaya yazılamadı (geçici sunucu sorunu) | Aynı clientFeedbackIdentifier ile biraz sonra tekrar dene |
UserNotFound | Kullanıcı bulunamadı ya da pasif | Oturumu kapatıp yeniden giriş iste |
Unauthorized | Token geçerli ama kullanıcı kimliği okunamadı | Yeniden giriş yap |
FeedbackTopicsNotConfigured | Sunucuda 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)
}
metadata kullan:
form.AddField("metadata", JsonUtility.ToJson(myInfo));
(JsonUtility.ToJson nesne üretir; en fazla 8192 bayt).
Tarayıcıdan denemek (Execute)
- İnteraktif Referans'ta Auth → Login → Test Request ile giriş yap ve dönen
accessToken'ı kopyala. - 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.
- Feedback → Geri bildirim gönder → Test Request: Request Body → Multipart Form.
topicCodesatırının Value'suna ör.bugyaz; istersenrating,message,clientFeedbackIdentifierdoldur;filessatırında Select File ile bir PNG seç → Send. Boş bırakılan satırlar gönderilmemiş sayılır. - Aynı
clientFeedbackIdentifierile ikinci kez Send: aynıfeedbackIdentifierveisIdempotentReplay: truegelir. - Hata örnekleri:
topicCodevecustomTopic'i boşaltıncaTopicRequired,rating'e7yazıncaInvalidRatinggelir.