Firebase Cloud Messaging'den (FCM) Pushizo'ya göç

Bildirimleri doğrudan Firebase Cloud Messaging (FCM HTTP v1 API, Firebase Admin SDK ya da Firebase konsolu) ile gönderiyorsanız bu rehber Pushizo'ya geçişi anlatır. Pushizo Android'de FCM'i taşıma katmanı olarak kullanmaya devam eder; iOS'ta doğrudan APNs'e, web'de standart Web Push'a (VAPID) gönderir. Dolayısıyla Firebase projeniz ve mevcut Android token'larınız geçerliliğini korur.

1. Neler değişirBağlantıyı kopyala

2. Kanal kurulumuBağlantıyı kopyala

Android (android_push)Bağlantıyı kopyala

1. Firebase konsolu → Project settings → Service accounts → Generate new private key ile servis hesabı JSON'unu indirin (firebase-adminsdk-…json). Zaten Admin SDK ile gönderim yapıyorsanız aynı dosyadır.
2. Dashboard → Kanallar → Android Push → JSON'u yükleyin → Doğrula (POST /v1/apps/{app_id}/channels/android_push/validate FCM'e test bağlantısı yapar). Dosya envelope encryption ile saklanır ve hiçbir yanıtta dönmez.
3. API ile: PUT /v1/apps/{app_id}/channels/android_push { "provider": "fcm", "service_account": { …JSON nesnesi ya da dosya içeriği metni… } } (admin kapsamı; proje değişiyorsa confirm_project_change: true).

Servis hesabı aynı Firebase projesine ait olduğu sürece uygulamanızdaki mevcut FCM token'ları Pushizo'dan de teslim alır. SENDER_ID_MISMATCH hatası görürseniz servis hesabı başka projeye aittir.

iOS (ios_push)Bağlantıyı kopyala

Firebase iOS SDK'sı APNs token'ını FCM token'ına çevirir; Pushizo bu dolaylamayı kullanmaz. Apple Developer → Keys → APNs anahtarı (.p8), Key ID, Team ID ve Bundle ID'yi Kanallar → iOS Push ekranına girin; ortam olarak Xcode derlemesi için sandbox, TestFlight/App Store için production seçin. Uygulamada Firebase Messaging'i kaldırabilir, FirebaseApp.configure()'ı yalnızca Analytics/Crashlytics için tutabilirsiniz.

Web (web_push)Bağlantıyı kopyala

Kanallar → Web Push etkinleştirildiğinde Pushizo bir VAPID çifti üretir. Firebase'in VAPID anahtarıyla oluşturulmuş tarayıcı abonelikleri taşınamaz; ziyaretçiler Pushizo Web SDK'sı ile yeniden abone olur (izin verilmişse autoResubscribe ile sessizce).

3. Token'ların taşınmasıBağlantıyı kopyala

Seçenek A — SDK ile yeniden kayıt (önerilen)Bağlantıyı kopyala

Pushizo SDK'ları ilk açılışta cihazı POST /sdk/v1/apps/{app_id}/subscriptions ile kaydeder; Android'de token FirebaseMessaging.getInstance().token üzerinden alınır, iOS'ta didRegisterForRemoteNotificationsWithDeviceToken ile SDK'ya verilir. Kullanıcı kimliğini bildiğiniz anda Pushizo.login(externalId) çağırın; böylece tüm cihazlar aynı kullanıcıda birleşir. Bu yol ek veri aktarımı gerektirmez; aktif kullanıcılar uygulamayı açtıkça Pushizo'ya geçer.

Seçenek B — CSV içe aktarma (csv_users)Bağlantıyı kopyala

Uygulama açılmadan da hedeflenebilsin istiyorsanız kendi veritabanınızdaki FCM token'larını Pushizo CSV biçiminde dışa aktarıp yükleyin (Firebase'in token'ları dışa aktaran bir API'si yoktur; token'lar sizin sunucunuzdadır).

external_id,channel,token,language,timezone,tag.topic_news,tag.plan
u-1001,android_push,dGhpcyBpcyBhIHRva2Vu…,tr,Europe/Istanbul,1,pro
u-1002,android_push,YW5vdGhlciB0b2tlbg…,en,Europe/London,,free
u-1003,,,tr,,1,

curl -X POST "https://api.example.com/v1/apps/app_…/imports" \
  -H "Authorization: Bearer hs_live_…" -F type=csv_users -F file=@fcm-tokens.csv

İş tamamlanınca stats (processed, created_users, updated_users, created_subscriptions, skipped, errors) ve hatalı satırlar için error_report_url döner. İçe aktarma idempotenttir; (app, channel, token) benzersiz olduğundan aynı token ikinci kez yüklendiğinde güncellenir. Toplu içe aktarma webhook üretmez. Sınır: 50 MB, 500.000 satır (IMPORT_MAX_ROWS); daha büyük dosyaları bölün.

Token FCM tarafından geçersiz bulunursa (UNREGISTERED) ilk gönderimde abonelik otomatik invalid olur; eski token'ları önceden temizlemeniz gerekmez.

4. Topic ve condition → segment / tagBağlantıyı kopyala

FCM topic'lerinin Pushizo'da karşılığı yoktur; aynı işlevi tag + segment ya da kategori tercihleri sağlar.

Segment önizleme (POST /v1/apps/{app_id}/segments/preview) sayım ve örnek kullanıcıları döndürür; bir hedef için gönderim yapmadan alıcı sayısı almak için POST /v1/notifications/estimate.

5. Mesaj gövdesi eşlemesiBağlantıyı kopyala

FCM HTTP v1 message nesnesi ile Pushizo POST /v1/notifications alanları:

Örnek (Firebase Admin SDK → Pushizo Node SDK):

// Önce (firebase-admin)
await admin.messaging().send({
  token,
  notification: { title: 'Siparişiniz yola çıktı', body: 'Takip bağlantısı içeride', image: 'https://cdn.example.com/box.png' },
  data: { order_id: '1001', screen: 'orders' },
  android: { priority: 'high', notification: { channelId: 'orders' } },
  apns: { payload: { aps: { sound: 'default', 'thread-id': 'orders' } } },
});

// Sonra (@pushizo/node)
await hs.notifications.create({
  idempotency_key: 'order-1001-shipped',
  target: { include_external_ids: [userId] },           // token yerine kullanıcı
  headings: { tr: 'Siparişiniz yola çıktı', en: 'Your order has shipped' },
  contents: { tr: 'Takip bağlantısı içeride', en: 'Tracking link inside' },
  big_picture: 'https://cdn.example.com/box.png',
  data: { order_id: '1001', screen: 'orders' },
  priority: 10,
  android_channel_id: 'orders',
  ios_sound: 'default',
  thread_id: 'orders',
});

Aynı istek Python/Go/Java/.NET/Ruby SDK'larında notifications.create ile yapılır; sunucu SDK'sı olmayan dillerde curl:

curl -X POST https://api.example.com/v1/notifications \
  -H "Authorization: Bearer hs_live_…" -H "Content-Type: application/json" -H "Idempotency-Key: order-1001-shipped" \
  -d '{"app_id":"app_…","target":{"include_external_ids":["u-1001"]},"headings":{"tr":"Siparişiniz yola çıktı"},"contents":{"tr":"Takip bağlantısı içeride"},"data":{"order_id":"1001"}}'

Data (sessiz) mesajlarBağlantıyı kopyala

• FCM data-only mesajı: Pushizo'da content_available: true + data. Android SDK bildirim göstermez; iOS'ta apns-push-type: background ile gönderilir (aps.content-available: 1). iOS arka plan push'larında Apple'ın saat başına birkaç mesaj sınırı geçerlidir.
• Uygulamanızda FirebaseMessagingService.onMessageReceived içinde yaptığınız özel işleme Pushizo'da Pushizo.Notifications.addForegroundLifecycleListener (ön plan) ve addClickListener (tıklama, event.notification.data) ile taşınır. Kendi FirebaseMessagingService sınıfınız kalacaksa manifestte yalnızca biri FCM mesajlarını alır; Pushizo'nun PushizoMessagingService'i manifest merge ile eklenir, kendi servisinizi kaldırın ya da Pushizo dışı mesajları ayırt etmek için data.hs_delivery_id alanına bakın.

6. Analitik farklarıBağlantıyı kopyala

Firebase Analytics olaylarını (notification_receive, notification_open) kullanan panolarınız varsa, Pushizo webhook'larını (delivery.*) kendi veri ambarınıza yazarak aynı metrikleri üretebilirsiniz; olaylar Pushizo-Event-Id ile tekilleştirilir.

7. Geçiş sırasıBağlantıyı kopyala

1. Kanalları kurup doğrulayın; bir test cihazını Test cihazı yapıp Mesajlar → Test push gönder ile teslimatı görün.
2. Sunucu tarafında gönderimleri Pushizo'ya taşıyın (önce işlemsel bildirimler, sonra toplu kampanyalar). Topic bazlı gönderimleri segmentlere çevirin.
3. Android/iOS uygulamalarına Pushizo SDK'sını ekleyip (docs/sdk/android.md, docs/sdk/ios.md) yeni sürümü yayınlayın; login(externalId) çağrısını kimlik doğrulama akışına koyun.
4. Eski sürümlerdeki kullanıcılar için (SDK'sız) Seçenek B ile token'ları içe aktarın; yeni sürüm yayıldıkça bu kayıtlar SDK kayıtlarıyla (app, channel, token) üzerinden birleşir.
5. Firebase konsolundan/Admin SDK'dan gönderimi durdurun; servis hesabı anahtarını yalnızca Pushizo'da bırakın.