Ö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.
Hazırlık (bir kez)
| Konu | Ne yapılır |
|---|---|
| SDK | En 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ç – Android | AndroidManifest.xml içine: <meta-data android:name="firebase_messaging_installation_id_enabled" android:value="true" /> |
| FID kaydını aç – iOS | Info.plist içine FirebaseMessagingInstallationIdEnabled = YES (Unity'de bir PostProcessBuild script'iyle eklenebilir). |
| Minimum sürüm | iOS 15.0 (proje şu an 13.0 hedefliyor; yükseltilmeli). Android min SDK 24. |
| Bildirim izni | Android 13 ve üstünde POST_NOTIFICATIONS çalışma zamanı izni; iOS'ta bildirim izni (ve APNs entitlement). |
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ış
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.
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.
Çı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).
| Alan | Zorunlu | Kural |
|---|---|---|
platform | Evet | Android veya Ios. |
targetKind | Evet | Her zaman Fid. Eski RegistrationToken (deprecated TokenReceived) kabul edilmez → UnsupportedTargetKind. |
targetValue | Evet | e.InstallationId (FID). 1–256 karakter, boşluksuz yazdırılabilir ASCII. Hiçbir yanıtta geri dönmez. |
permissionStatus | Evet | Granted, Provisional (yalnız iOS), Denied veya NotDetermined. İzinsiz cihaz da kaydedilir ama bildirim almaz; izin verilince tekrar PUT yeterli. |
appVersion | Hayır | Application.version; en fazla 64 karakter. |
{
"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ı
| Durum | Sonuç |
|---|---|
Aynı öğrenci, aynı FID ile tekrar PUT | Kayıt çoğalmaz; izin/sürüm güncellenir; bindingIdentifier aynı kalır. |
| Firebase yeni FID verdi | Kayı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 silindi | Backend bütün bağlantıları kapatır. Hesap yeniden aktifleşirse sonraki girişteki PUT yeterlidir. |
30 gün PUT gelmeyen kayıt | Bildirim 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).
| statusCode | Uç | Ne zaman | İstemci ne yapmalı |
|---|---|---|---|
InvalidDeviceInstallationIdentifier | PUT, DELETE | Route'taki deviceInstallationId boş olmayan bir GUID değil (ör. FID route'a kondu) | Cihaz kurulum GUID'ini kullan |
InvalidPlatform | PUT | platform Android/Ios değil ya da gövde yok | İstemci hatası |
UnsupportedTargetKind | PUT | targetKind Fid değil | Fid gönder; TokenReceived kullanma |
InvalidTargetValue | PUT | FID boş, 256 karakterden uzun ya da boşluk/ASCII dışı karakter içeriyor | e.InstallationId'yi olduğu gibi gönder |
InvalidPermissionStatus | PUT | İzin değeri tanınmıyor | Dört değerden birini gönder |
AppVersionTooLong | PUT | appVersion 64 karakteri aşıyor | Kırp |
InvalidBindingIdentifier | DELETE | bindingIdentifier yok ya da GUID değil | Saklanan değeri gönder; yoksa DELETE çağırmadan çıkış yap |
PushRegistrationUnavailable | PUT, DELETE | Sunucuda push kaydı yapılandırılmamış | Sessizce geç; sonraki açılışta tekrar dene. Ekibe bildir |
UserNotFound | PUT | Öğrenci bulunamadı ya da pasif | Oturumu kapatıp yeniden giriş iste |
Unauthorized | PUT, DELETE | Token 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 durumu | permissionStatus |
|---|---|
| iOS Authorized / Android 13+ izin verildi / Android 12 ve altı | Granted |
| iOS Provisional | Provisional |
| Kullanıcı reddetti | Denied |
| Henüz sorulmadı | NotDetermined |
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 |
|---|---|
schemaVersion | Her zaman "1"; alanlar değişirse artar. |
notificationType | assignment.new, assignment.due-soon, streak.at-risk ya da test için push.smoke. |
referenceType / referenceIdentifier | Varsa 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. |
deliveryIdentifier | Bu 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.
| Bildirim | Ne zaman | Metin |
|---|---|---|
assignment.new | Ödev öğrencilere açıldığında (07:30–22:30 arası) | Yeni ödevin hazır 📚 / Okuma parçaların seni bekliyor. |
assignment.due-soon | Teslimden önceki gün 18:00, teslim etmemiş öğrencilere | Ödevinin son günü yarın ⏰ / Bitirmek için hâlâ vaktin var. |
streak.at-risk | 19:00, en az 3 günlük serisi bugün bozulacak öğrencilere | 🔥 {n} günlük serin bitmesin! / Bugünkü oturumunu tamamla, serini koru. |
Tarayıcıdan denemek (Execute)
- İnteraktif Referans'ta Auth → Login ile giriş yap ve
accessToken'ı Bearer Token alanına yapıştır. - Me → Push kaydı oluştur/yenile:
deviceInstallationId'ye yeni bir GUID yaz; gövdeye yukarıdaki örneği koy (targetValueolarak ör.postman-test-fid-1) → Send. DönenbindingIdentifier'ı not al. - Aynı isteği tekrar gönder:
bindingIdentifieraynı kalır.targetValue'yu değiştirip gönder: yenilenir. - Me → Push kaydını kaldır: aynı
deviceInstallationIdve sonbindingIdentifier→isRemoved: true. Tekrar gönder →isRemoved: false.
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.