Özellikler

Push Bildirimleri (FCM)

Bildirimler doğrudan Firebase Cloud Messaging (FCM) ile gönderilir. Uygulama Firebase'den aldığı Firebase Installation ID'yi (FID) backend'e kaydeder; backend onu giriş yapan öğrenciyle ilişkilendirir ve bildirimi o öğrencinin tüm aktif cihazlarına gönderir. Kayıt uçları Bearer ister; yollar /api/me/push-installations ile başlar.

OneSignal kaldırılıyor Backend artık OneSignal üzerinden gönderim yapmaz. FCM kaydını backend'e iletmeyen eski sürümler bildirim alamaz. OneSignal SDK'sı FCM build'inden çıkarılmalıdır: iki SDK birlikte kalırsa Android'de mesajı alan servis, iOS'ta APNs tarafı çakışabilir.

Hazırlık (bir kez)

KonuNe yapılır
SDKEn güncel Firebase Unity SDK'sının FirebaseMessaging paketi (Ekim 2026 itibarıyla 14.x; Unity 2022.3 LTS ve üstü).
Yapılandırma dosyalarıBackend ekibinden alınan güncel google-services.json (Android com.cozum.cozumhap) ve GoogleService-Info.plist (iOS com.superz.okurada). Firebase projesi okurada-1964a.
FID kaydını aç – AndroidAndroidManifest.xml içine: <meta-data android:name="firebase_messaging_installation_id_enabled" android:value="true" />
FID kaydını aç – iOSInfo.plist içine FirebaseMessagingInstallationIdEnabled = YES (Unity'de bir PostProcessBuild script'iyle eklenebilir).
Minimum sürümiOS 15.0 (proje şu an 13.0 hedefliyor; yükseltilmeli). Android min SDK 24.
Bildirim izniAndroid 13 ve üstünde POST_NOTIFICATIONS çalışma zamanı izni; iOS'ta bildirim izni (ve APNs entitlement).
FID ile cihaz kurulum GUID'i ayrı şeylerdir Firebase'in RegistrationReceived event'indeki e.InstallationId FID'dir ve isteğin gövdesinde targetValue olarak gönderilir. Route'taki {deviceInstallationId} ise uygulamanın kurulum başına kendisinin ürettiği rastgele GUID'dir. FID'yi route'a koyarsan istek InvalidDeviceInstallationIdentifier ile reddedilir.

Cihaz kurulum GUID'i (deviceInstallationId)

Uygulama ilk açılışta bir kez Guid.NewGuid() üretir ve PlayerPrefs'e yazar; sonra hep aynısını kullanır. Hesaba göre değişmez, girişte/çıkışta yeniden üretilmez. Donanım kimliği kullanılmaz. Uygulama silinip yeniden kurulunca yeni GUID üretilmesi normaldir.

Akış

1

FID'yi dinle ve sakla

Uygulama açılışında FirebaseMessaging.RegistrationReceived'a abone ol. Event, Firebase hazır olduğunda ve FID değiştiğinde gelir; gelen e.InstallationId'yi PlayerPrefs'e yaz. Event girişten önce gelebilir; bu yüzden değer saklanır ve giriş sonrasında kullanılır.

2

Kaydet / yenile

PUT /api/me/push-installations/{deviceInstallationId}

Şu durumlarda çağır (oturum açıkken ve FID biliniyorken): girişten hemen sonra, her uygulama açılışında, yeni FID geldiğinde ve bildirim izni değiştiğinde (izin penceresinin sonucu dahil). Tekrar çağırmak kayıt çoğaltmaz. Yanıttaki bindingIdentifier'ı her seferinde sakla; değer değişebilir.

3

Çıkışta kaldır

DELETE /api/me/push-installations/{deviceInstallationId}?bindingIdentifier=…

Kullanıcı çıkış yapmadan önce, token hâlâ geçerliyken çağır; sonra saklanan bindingIdentifier'ı sil. İstek başarısız olsa bile (ör. ağ yok) çıkışı engelleme: aynı cihazda bir sonraki giriş bağlantıyı yeni hesaba taşır. Hesap silmede (DELETE /api/auth/account) ayrıca çağırmak gerekmez; backend o hesabın bütün bağlantılarını kendisi kapatır. Cihaz kurulum GUID'i ve FID silinmez.

Kayıt isteği

Gövde JSON'dur. Kod değerleri büyük/küçük harf duyarsızdır (iOS, ios da kabul edilir).

AlanZorunluKural
platformEvetAndroid veya Ios.
targetKindEvetHer zaman Fid. Eski RegistrationToken (deprecated TokenReceived) kabul edilmez → UnsupportedTargetKind.
targetValueEvete.InstallationId (FID). 1–256 karakter, boşluksuz yazdırılabilir ASCII. Hiçbir yanıtta geri dönmez.
permissionStatusEvetGranted, Provisional (yalnız iOS), Denied veya NotDetermined. İzinsiz cihaz da kaydedilir ama bildirim almaz; izin verilince tekrar PUT yeterli.
appVersionHayırApplication.version; en fazla 64 karakter.
İstek gövdesi
{
  "platform": "Android",
  "targetKind": "Fid",
  "targetValue": "<e.InstallationId>",
  "permissionStatus": "Granted",
  "appVersion": "3.4.1"
}
Cevap (data)
{
  "deviceInstallationIdentifier": "2f1c6b8e-3a54-4b7e-9d0a-8f2b1c4d5e6f",
  "bindingIdentifier": "9a7d3c21-0b6e-4f58-a1c2-7e9f0d3b4a56"
}

Başarılı cevap, FID'nin Firebase tarafından kabul edildiği anlamına gelmez; yalnız backend kaydının yapıldığını gösterir.

Bağlantı kuralları

DurumSonuç
Aynı öğrenci, aynı FID ile tekrar PUTKayıt çoğalmaz; izin/sürüm güncellenir; bindingIdentifier aynı kalır.
Firebase yeni FID verdiKayıt güncellenir; bindingIdentifier yenilenir.
Aynı cihazda başka hesapla girişKurulum yeni öğrenciye geçer; eski öğrenci o cihazdan bildirim almaz; bindingIdentifier yenilenir.
Çıkıştan sonra tekrar girişBağlantı yeniden açılır; bindingIdentifier yenilenir. Böylece gecikmiş eski bir DELETE yeni girişi kapatamaz.
Öğrencinin iki cihazıİki ayrı kayıt; bildirim ikisine de gider. Birinin çıkışı diğerini etkilemez.
Öğrenci pasifleştirildi / hesap silindiBackend bütün bağlantıları kapatır. Hesap yeniden aktifleşirse sonraki girişteki PUT yeterlidir.
30 gün PUT gelmeyen kayıtBildirim almaz; sonraki PUT ile yeniden açılır. Her açılışta PUT çağırmanın sebebi budur.

Hata kodları

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

statusCodeUçNe zamanİstemci ne yapmalı
InvalidDeviceInstallationIdentifierPUT, DELETERoute'taki deviceInstallationId boş olmayan bir GUID değil (ör. FID route'a kondu)Cihaz kurulum GUID'ini kullan
InvalidPlatformPUTplatform Android/Ios değil ya da gövde yokİstemci hatası
UnsupportedTargetKindPUTtargetKind Fid değilFid gönder; TokenReceived kullanma
InvalidTargetValuePUTFID boş, 256 karakterden uzun ya da boşluk/ASCII dışı karakter içeriyore.InstallationId'yi olduğu gibi gönder
InvalidPermissionStatusPUTİzin değeri tanınmıyorDört değerden birini gönder
AppVersionTooLongPUTappVersion 64 karakteri aşıyorKırp
InvalidBindingIdentifierDELETEbindingIdentifier yok ya da GUID değilSaklanan değeri gönder; yoksa DELETE çağırmadan çıkış yap
PushRegistrationUnavailablePUT, DELETESunucuda push kaydı yapılandırılmamışSessizce geç; sonraki açılışta tekrar dene. Ekibe bildir
UserNotFoundPUTÖğrenci bulunamadı ya da pasifOturumu kapatıp yeniden giriş iste
UnauthorizedPUT, DELETEToken geçerli ama kullanıcı kimliği okunamadıYeniden giriş yap

DELETE bağlantı zaten kapalıysa, başka hesaba ya da daha yeni bir bağlantıya aitse hata vermez: isSuccess: true, data.isRemoved: false döner. Token hiç yoksa ya da süresi dolmuşsa cevap HTTP 401'dir (envelope yok).

Unity örneği

Modeller (JsonUtility)
[Serializable] public class PushRegistrationBody { public string platform; public string targetKind; public string targetValue; public string permissionStatus; public string appVersion; }
[Serializable] public class PushInstallationData { public string deviceInstallationIdentifier; public string bindingIdentifier; }
[Serializable] public class PushInstallationResponse { public bool isSuccess; public string statusCode; public string message; public PushInstallationData data; }
Kurulum GUID'i ve FID'nin saklanması
const string DeviceInstallationKey = "readhaven.push.deviceInstallationId";
const string FidKey = "readhaven.push.fid";
const string BindingKey = "readhaven.push.bindingIdentifier";

static string DeviceInstallationId()
{
    var id = PlayerPrefs.GetString(DeviceInstallationKey, "");
    if (string.IsNullOrEmpty(id))
    {
        id = Guid.NewGuid().ToString();
        PlayerPrefs.SetString(DeviceInstallationKey, id);
        PlayerPrefs.Save();
    }
    return id;
}

void Start()
{
    Firebase.Messaging.FirebaseMessaging.RegistrationReceived += OnRegistrationReceived;
}

void OnRegistrationReceived(object sender, Firebase.Messaging.RegistrationReceivedEventArgs e)
{
    PlayerPrefs.SetString(FidKey, e.InstallationId); // FID
    PlayerPrefs.Save();
    if (IsLoggedIn) StartCoroutine(RegisterPush(AccessToken)); // oturum açıksa hemen kaydet
}
İzin durumu

Değer, işletim sisteminin gerçek izin durumundan okunur. Projede kurulu olan Unity Mobile Notifications paketi bunu verir; eşleme şöyledir:

İşletim sistemi durumupermissionStatus
iOS Authorized / Android 13+ izin verildi / Android 12 ve altıGranted
iOS ProvisionalProvisional
Kullanıcı reddettiDenied
Henüz sorulmadıNotDetermined
Kaydet (PUT)
IEnumerator RegisterPush(string accessToken)
{
    var fid = PlayerPrefs.GetString(FidKey, "");
    if (string.IsNullOrEmpty(fid) || string.IsNullOrEmpty(accessToken)) yield break; // FID henüz gelmedi

    var body = new PushRegistrationBody
    {
        platform = Application.platform == RuntimePlatform.IPhonePlayer ? "Ios" : "Android",
        targetKind = "Fid",
        targetValue = fid,
        permissionStatus = ReadPermissionStatus(), // yukarıdaki eşleme
        appVersion = Application.version,
    };

    var url = "https://api.readhaven.co/api/me/push-installations/" + DeviceInstallationId();
    using var req = UnityWebRequest.Put(url, JsonUtility.ToJson(body));
    req.SetRequestHeader("Content-Type", "application/json");
    req.SetRequestHeader("Authorization", "Bearer " + accessToken);
    yield return req.SendWebRequest();
    if (req.result != UnityWebRequest.Result.Success) yield break; // ağ hatası/401: sonraki açılışta tekrar

    var res = JsonUtility.FromJson<PushInstallationResponse>(req.downloadHandler.text);
    if (res.isSuccess)
    {
        PlayerPrefs.SetString(BindingKey, res.data.bindingIdentifier);
        PlayerPrefs.Save();
    }
}
Çıkışta kaldır (DELETE)
IEnumerator UnregisterPush(string accessToken)
{
    var binding = PlayerPrefs.GetString(BindingKey, "");
    if (!string.IsNullOrEmpty(binding))
    {
        var url = "https://api.readhaven.co/api/me/push-installations/" + DeviceInstallationId()
                  + "?bindingIdentifier=" + UnityWebRequest.EscapeURL(binding);
        using var req = UnityWebRequest.Delete(url);
        req.downloadHandler = new DownloadHandlerBuffer(); // Delete() varsayılan olarak cevap okumaz
        req.SetRequestHeader("Authorization", "Bearer " + accessToken);
        req.timeout = 5;
        yield return req.SendWebRequest(); // sonuç ne olursa olsun çıkışa devam
    }

    PlayerPrefs.DeleteKey(BindingKey); // cihaz kurulum GUID'i ve FID kalır
    PlayerPrefs.Save();
    // ... token'ı sil, giriş ekranına dön
}

Bildirim içeriği

Her bildirim görünür bir başlık/metin ve data alanları taşır. Android ikonu ve kanalı uygulamanın varsayılanlarıdır (default_notification_icon, default_notification_channel_id); backend ikon, renk veya kanal göndermez. Bildirim metninde öğrenci adı, puan veya ödevi veren öğretmen bilgisi bulunmaz.

data anahtarıDeğer
schemaVersionHer zaman "1"; alanlar değişirse artar.
notificationTypeassignment.new, assignment.due-soon, streak.at-risk ya da test için push.smoke.
referenceType / referenceIdentifierVarsa ilgili kayıt (ör. assignment + ödev ID'si). Seri ve test bildiriminde yoktur; alan hiç gönderilmez.
notificationIdentifierÖğrenci bildiriminin ID'si (GUID). Aynı bildirimin tekrarları cihazda tek bildirime iner.
deliveryIdentifierBu cihaza gönderimin ID'si (GUID).

Tüm değerler metindir (FCM kuralı). Uygulama bilmediği anahtarları yok saymalıdır. Bugün her bildirime dokunma uygulamayı aynı ekranda açar; tür bazlı yönlendirme istenirse notificationType ve referenceIdentifier kullanılabilir.

BildirimNe zamanMetin
assignment.newÖdev öğrencilere açıldığında (07:30–22:30 arası)Yeni ödevin hazır 📚 / Okuma parçaların seni bekliyor.
assignment.due-soonTeslimden önceki gün 18:00, teslim etmemiş öğrencilereÖdevinin son günü yarın ⏰ / Bitirmek için hâlâ vaktin var.
streak.at-risk19:00, en az 3 günlük serisi bugün bozulacak öğrencilere🔥 {n} günlük serin bitmesin! / Bugünkü oturumunu tamamla, serini koru.
Gönderim kuralları 23:00–07:30 (İstanbul) arasında bildirim gönderilmez; öğrenci günde en fazla 2 bildirim alır (cihaz sayısından bağımsız). Senaryolar kademeli olarak açılır. Uygulamanın yerel hareketsizlik hatırlatmaları backend'den gönderilmez; Unity'de kalır.

Tarayıcıdan denemek (Execute)

  1. İnteraktif Referans'ta Auth → Login ile giriş yap ve accessToken'ı Bearer Token alanına yapıştır.
  2. Me → Push kaydı oluştur/yenile: deviceInstallationId'ye yeni bir GUID yaz; gövdeye yukarıdaki örneği koy (targetValue olarak ör. postman-test-fid-1) → Send. Dönen bindingIdentifier'ı not al.
  3. Aynı isteği tekrar gönder: bindingIdentifier aynı kalır. targetValue'yu değiştirip gönder: yenilenir.
  4. Me → Push kaydını kaldır: aynı deviceInstallationId ve son bindingIdentifier → isRemoved: true. Tekrar gönder → isRemoved: false.
Gerçek kayıt oluşur Execute ile yapılan kayıtlar canlı veritabanına yazılır. Test kullanıcısı ve uydurma bir targetValue kullan; denemeyi DELETE ile kapat. Uydurma değer gönderim aşamasında Firebase tarafından reddedilir ve kayıt kendiliğinden kapanır.

Gerçek cihazda test bildirimi

Kayıt tamamlandıktan sonra cihaza gerçek bir bildirim gönderip görünümü ve dokunma davranışını sınamak için TestOps sayfasındaki POST /api/test-ops/users/{userIdentifier}/push-test kullanılır. Bildirim normal bildirimlerle aynı yoldan gider; notificationType değeri push.smoke olur. Yalnız backend'in test listesindeki öğrencilere gönderilebilir.

Alan bazlı tam şema Request/response alanlarının tamamı İnteraktif API Referansı'nda (Me bölümü) yer alır.