Notifications and Device Token Lifecycle

Notification entegrasyonu iki parçadan oluşur: cihaz token lifecycle'ı ve kullanıcı notification inbox lifecycle'ı. Push token kaydı uygulama açılışı, login sonrası, token rotate olduğunda ve izin durumu değiştiğinde güncellenmelidir.

Device token kaydı

POST /api/v1/notifications/device-token
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "token": "fcm-token",
  "platform": "ios",
  "deviceId": "iphone-15-pro-max",
  "timezone": "Europe/Istanbul",
  "liveActivityPushToStartToken": "activitykit-push-to-start-token"
}

Endpoint auth olmadan da çağrılabilir, fakat user ile ilişkilendirme ve timezone update için access token gönderilmelidir.

Ne zaman çağrılmalı?

1. Login veya registration tamamlandıktan sonra.
2. Uygulama açılışında token mevcutsa.
3. Firebase token rotate olduğunda.
4. Kullanıcı push iznini sonradan verdiğinde.
5. iOS Live Activity push-to-start token değiştiğinde.
6. Timezone değişimi algılandığında.

Token boş olsa bile timezone veya Live Activity alanları için request atılabilir. Backend boş token durumunda uygun alanları güncelleyip data=null döndürebilir.

Token silme

Logout, push izni kapatma veya token invalidate durumunda:

DELETE /api/v1/notifications/device-token/{token}
Authorization: Bearer <accessToken>

Başarılı silme 204 No Content dönebilir. Client response body beklememelidir.

Live Activity session

iOS remote-start sonrası runtime update token oluştuğunda session kaydedilir.

POST /api/v1/notifications/live-activity-sessions
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "streamId": "65f000000000000000000001",
  "deviceId": "iphone-15-pro-max",
  "liveActivityToken": "runtime-update-token",
  "activityId": "optional-local-activity-id"
}

Activity bittiğinde veya cihazdaki activity kapandığında:

DELETE /api/v1/notifications/live-activity-sessions/{streamId}/{deviceId}
Authorization: Bearer <accessToken>

Notification inbox

Kullanıcıya gösterilecek notification listesi için v2 endpoint tercih edilmelidir.

GET /api/v2/notifications?page=1&limit=20
Authorization: Bearer <accessToken>

Response paginated formatla döner: data.list notification item'ları, data.pagination meta bilgisidir.

Notification okundu işaretlemek için:

PATCH /api/v1/notifications/{id}/read
Authorization: Bearer <accessToken>
Content-Type: application/json

{
  "isRead": true
}

Client state önerisi

• Push permission state'i local state'te tutulur, backend source-of-truth olarak device token kaydı kullanılır.
• Aynı deviceId için yeni token geldiğinde eski token otomatik temizlenebilir; client yine de logout'ta delete çağırmalıdır.
• Bildirim ayarları push token kaydından bağımsızdır. Kategori bazlı kapatma backend notification preference akışıyla yönetilir.
• Notification inbox pagination ve push arrival event'i ayrı düşünülmelidir; push geldiğinde inbox ilk sayfası invalidate edilebilir.