Firebase Cloud Messaging ve FCM Token Kullanim Raporu

1. Amac ve Kapsam

Bu rapor, backend tarafında Firebase Cloud Messaging (FCM) altyapisini ve FCM token yasam dongusunu nasil kullandigimizi açıklar. Icerik, dogrudan kod tabanindaki mevcut implementasyona dayanir.

2. Mimari Ozet

• FCM entegrasyonu FirebaseModule ile global provider olarak ayaga kaldirilir.
• Bildirim gönderimi PushNotificationService tarafında yapilir.
• Token kayit/guncelleme/silme PushNotificationsController + DeviceTokenService + DeviceTokenRepository zincirinde yonetilir.
• Is kurali tarafında uygulama ici olaylardan gelen bildirimler NotificationDeliveryService ile push + in-app olarak orkestre edilir.

3. Firebase Admin Baslatma Akisi

FirebaseModule içinde kimlik bilgisi (service account) su oncelikle cozulur:

1. FIREBASE_ADMIN_SA_BASE64 (base64 json)
2. FIREBASE_PROJECT_ID + FIREBASE_CLIENT_EMAIL + FIREBASE_PRIVATE_KEY
3. FIREBASE_ADMIN_SA_PATH dosya yolu
4. Son fallback olarak repodaki src/config/firebase-service-account.json

Ardindan admin.initializeApp(...) ile app olusturulur ve app.messaging() DI ile enjekte edilir.

4. Endpoint ve Erisim Modeli

• Uygulama global prefix + versioning kullaniyor: /api/v1/...
• Device token endpointleri:
  • POST /api/v1/notifications/device-token
  • DELETE /api/v1/notifications/device-token/:token
• Test endpointleri:
  • POST /api/v1/notifications/test
  • POST /api/v1/notifications/test/username
• Broadcast endpointi:
  • POST /api/v1/notifications/admin/broadcast (admin role gerekli)

Not: JwtAuthGuard global olarak aktif oldugu için @Public olmayan endpointlerde JWT zorunludur.

5. FCM Token Yasam Dongusu

5.1 Kayit/Güncelleme

POST /notifications/device-token çağrısı ile:

• timezone geldiyse ve userId varsa kullanıcının timezone bilgisi guncellenir.
• token trim edilerek normalize edilir.
• Token bossa DB upsert yapilmaz (sadece timezone güncellemesi olur).
• Token varsa upsertByToken ile kayit/guncelleme yapilir.
• Ayni token için duplicate kayitlar temizlenir.
• Ayni userId + deviceId için eski tokenlar temizlenir (yeni token dışındakiler silinir).

5.2 Silme

DELETE /notifications/device-token/:token çağrısı:

• Token normalize edilir.
• userId varsa silme filtresi token + userId ile yapilir; bu sayede kullanıcı baskasinin tokenini silemez.

5.3 Okuma ve Toplu Islem

• Kullanıcı bazli tokenlar: findDistinctTokensByUser
• Tüm tokenlar: findDistinctAllTokens
• Token sahibi user listesi: findDistinctUserIdsWithTokens

6. Push Gonderim Akisi

6.1 Tekli/Test Gonderim

sendTestNotification:

• Token cozumu:
  • DTO'da token varsa direkt onu kullanir
  • Yoksa userId veya current user tokenlari kullanılır
• Mesaj formati:
  • notification.title/body
  • data payload string'e cevrilir
  • Android: priority=high, restrictedPackageName
  • iOS(APNS): apns-topic, content-available=true, sound=default

6.2 Is Kuralı Kaynakli Gonderim

sendNotificationByAction:

• Hedef kullanıcının tokenlari çekilir.
• Token yoksa sessizce 0 success / 0 failure döner.
• Varsa multicast gönderim yapar.
• Opsiyonel imageUrl için Android ve APNS tarafında image alanlari set edilir.

6.3 Toplu Gonderim (Broadcast Push)

sendNotificationToAllUsers:

• Tüm tokenlar dedupe edilir.
• Batch boyutu 500 olacak sekilde parcali gönderim yapilir.
• Toplam basari/basarisizlik metrikleri toplanir.

6.4 Gecersiz Token Temizligi

Tüm gönderim akislari su FCM hata kodlarini gecersiz token olarak kabul eder:

• messaging/registration-token-not-registered
• messaging/invalid-registration-token

Bu tokenlar otomatik olarak removeInvalidTokens ile veritabanindan temizlenir.

7. NotificationDeliveryService ile Is Kuralı Entegrasyonu

NotificationDeliveryService.deliver(...) akisi:

1. Kullanıcı tercih kontrolu: userSettingsService.isNotificationEnabled(...)
2. Izin yoksa push ve in-app atlanir.
3. Izin varsa push gönderimi denenir.
4. Push hata verse bile in-app oluşturma devam eder.

Bu sayede push altyapisinda gecici sorun olsa da in-app bildirim kaydi olabildigince korunur.

8. FCM ve Tokenin Kullanildigi Baslica Is Senaryolari

• Takip bildirimi (follow-user.usecase.ts)
• Mesaj ve kredi transferi bildirimi (message.service.ts)
• Takip edilen kisinin yayin baslatmasi (following-activity-notification.service.ts)
• Yayin oncesi hatirlatmalar (live-stream-pre-start-notification.service.ts)
• Kullanıcıya yayin hatirlatma (live-stream-user-reminder-notification.service.ts)

Bu senaryolarin hepsi NotificationDeliveryService uzerinden ortak push/in-app zincirine girer.

9. Test Kapsami Ozet

Mevcut unit testler asagidaki kritik davranislari dogrular:

• Token normalize ve dedupe davranisi
• Gecersiz token temizligi
• Broadcast kanallarinin (push + in-app) birlikte calismasi
• Kullanıcı tercihleri kapalıyken bildirimin atlanmasi
• Push hatasi olsa bile in-app akisinin devam etmesi

10. Gozlemler

1. Dokumantasyonla kod davranisi arasinda bir fark var: bazi dokümanlarda device-token endpointi "opsiyonel auth" gibi anlatilsa da mevcut kodda endpoint @Public değil ve global JWT guard nedeniyle auth zorunlu.
2. Firebase credentials için repoda fallback service-account json bulunuyor. Guvenlik ve operasyon acisindan, production ortamında secret manager/env tabanli yonetim tercih edilmeli.

11. Kaynak Kod Referanslari

• src/integrations/firebase/firebase.module.ts
• src/config/firebase.config.ts
• src/notifications/push-notifications.controller.ts
• src/notifications/device-token.service.ts
• src/notifications/repository/device-token.repository.ts
• src/notifications/schemas/device-token.schema.ts
• src/notifications/push-notification.service.ts
• src/notifications/notification-delivery.service.ts
• src/user-settings/user-settings.service.ts
• src/auth/guards/jwt-auth.guard.ts
• src/main.ts
• src/follow/use-cases/follow-user.usecase.ts
• src/message/message.service.ts
• src/live-stream/services/following-activity-notification.service.ts
• src/live-stream/services/live-stream-pre-start-notification.service.ts
• src/live-stream/services/live-stream-user-reminder-notification.service.ts
• src/notifications/push-notification.service.spec.ts
• src/notifications/device-token.service.spec.ts
• src/notifications/notification-delivery.service.spec.ts