PushizoDocs
Migration

Migrating from Firebase Cloud Messaging (FCM) to Pushizo

If you send notifications directly with Firebase Cloud Messaging (the FCM HTTP v1 API, the Firebase Admin SDK or the Firebase console), this guide covers moving to Pushizo. On Android, Pushizo keeps using FCM as the transport layer…

If you send notifications directly with Firebase Cloud Messaging (the FCM HTTP v1 API, the Firebase Admin SDK or the Firebase console), this guide covers moving to Pushizo. On Android, Pushizo keeps using FCM as the transport layer; on iOS it sends directly to APNs, and on the web it uses standard Web Push (VAPID). As a result, your Firebase project and your existing Android tokens remain valid.

1. What changes

TopicSending directly with FCMPushizo
Android transportFCMFCM (the same Firebase project, with the service account JSON)
iOS transportFCM → APNs (requires the Firebase iOS SDK)Direct APNs (.p8 key); no Firebase iOS SDK needed
Web transportFCM web (Firebase VAPID key)Standard Web Push, with a VAPID pair generated by Pushizo
TargetingToken, topic, conditionUser (external_id), subscription, segment (tag/property/event filters), alias
User modelNone (you maintain your own token list)User + multiple subscriptions; device merging (login)
Scheduling, quiet hours, frequency cappingIn your own codePlatform features (send_after, delivery_time_of_day, app settings)
AnalyticsFirebase Analytics events (notification_receive, notification_open)Delivery timeline (queued → sent → received → opened), conversion attribution, webhook events
Email / SMS / in-app / notification inboxNoneIncluded

2. Channel setup

Android (android_push)

  1. In the Firebase console, go to Project settings → Service accounts → Generate new private key and download the service account JSON (firebase-adminsdk-…json). If you already send with the Admin SDK, it is the same file.
  2. Dashboard → Channels → Android Push → upload the JSON → Validate (POST /v1/apps/{app_id}/channels/android_push/validate makes a test connection to FCM). The file is stored with envelope encryption and is never returned in any response.
  3. With the API: PUT /v1/apps/{app_id}/channels/android_push { "provider": "fcm", "service_account": { …JSON object or file contents as text… } } (admin scope; confirm_project_change: true if the project changes).

As long as the service account belongs to the same Firebase project, the existing FCM tokens in your app also receive deliveries from Pushizo. If you see a SENDER_ID_MISMATCH error, the service account belongs to a different project.

iOS (ios_push)

The Firebase iOS SDK converts the APNs token into an FCM token; Pushizo does not use this indirection. In Apple Developer → Keys, get an APNs key (.p8) and enter it along with the Key ID, Team ID and Bundle ID on the Channels → iOS Push screen; choose sandbox as the environment for Xcode builds and production for TestFlight/App Store. You can remove Firebase Messaging from the app and keep FirebaseApp.configure() only for Analytics/Crashlytics.

Web (web_push)

When you enable Channels → Web Push, Pushizo generates a VAPID pair. Browser subscriptions created with Firebase's VAPID key cannot be migrated; visitors re-subscribe with the Pushizo Web SDK (silently with autoResubscribe if permission was already granted).

3. Migrating tokens

Option A — Re-registration through the SDK (recommended)

On first launch, the Pushizo SDKs register the device with POST /sdk/v1/apps/{app_id}/subscriptions; on Android the token is obtained from FirebaseMessaging.getInstance().token, and on iOS it is passed to the SDK in didRegisterForRemoteNotificationsWithDeviceToken. Call Pushizo.login(externalId) as soon as you know the user's ID; this merges all their devices into the same user. This path requires no additional data transfer; active users move over to Pushizo as they open the app.

Option B — CSV import (csv_users)

If you want users to be targetable even before they open the app, export the FCM tokens from your own database in the Pushizo CSV format and upload them (Firebase has no API for exporting tokens; the tokens live on your server).

ColumnValue
external_idYour user ID (required if there is no token)
channelandroid_push (Android FCM token), email, sms. ios_push only for raw APNs tokens (hex); iOS tokens from FCM cannot be imported. web_push cannot be imported via CSV.
tokenFCM registration token
statussubscribed (default), unsubscribed, invalid
language, timezonetr, Europe/Istanbul (IANA)
tags or tag.<key>A JSON object, or one tag per column (e.g. tag.topic_news)
properties or property.<key>User properties
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.pushizo.com/v1/apps/app_…/imports" \
  -H "Authorization: Bearer hs_live_…" -F type=csv_users -F file=@fcm-tokens.csv

When the job completes, it returns stats (processed, created_users, updated_users, created_subscriptions, skipped, errors) and an error_report_url for invalid rows. Imports are idempotent; because (app, channel, token) is unique, uploading the same token a second time updates it. Bulk imports do not produce webhooks. Limits: 50 MB, 500,000 rows (IMPORT_MAX_ROWS); split larger files.

If FCM reports a token as invalid (UNREGISTERED), the subscription automatically becomes invalid on the first send; you don't need to clean up old tokens beforehand.

4. Topics and conditions → segments / tags

FCM topics have no direct equivalent in Pushizo; tags + segments or category preferences serve the same purpose.

FCMPushizo
FirebaseMessaging.getInstance().subscribeToTopic("news")Pushizo.User.addTag("topic_news", "1") (SDK) or PATCH /v1/apps/{app_id}/users/by/external_id/{id} { "tags": { "topic_news": "1" } }
unsubscribeFromTopic("news")Pushizo.User.removeTag("topic_news") or { "tags": { "topic_news": null } }
Sending with "topic": "news"Segment definition: { "all": [{ "field": "tags.topic_news", "op": "eq", "value": "1" }] } → target.included_segments: ["seg_…"]; or the same definition in target.filters without saving it
"condition": "'news' in topics && 'tr' in topics"Segment AST all/any/none groups: { "all": [{ "field": "tags.topic_news", "op": "eq", "value": "1" }, { "field": "tags.topic_tr", "op": "eq", "value": "1" }] }
Topic subscriptions chosen by the userCategories (Dashboard → Audience → Categories) + User.setPreferences([{ category: "news", optedIn: true }]); a user who has opted out of a category does not receive messages in that category (suppression_reason: category_opt_out)
Sending to everyone ("topic": "all")target.all: true

Segment preview (POST /v1/apps/{app_id}/segments/preview) returns a count and sample users; to get the recipient count for a target without sending, use POST /v1/notifications/estimate.

5. Message body mapping

FCM HTTP v1 message object fields and their Pushizo POST /v1/notifications equivalents:

FCM v1PushizoNote
token / topic / conditiontarget.include_subscription_ids / target.include_external_ids / target.included_segments / target.filtersThe target object is required.
notification.title / notification.bodyheadings / contentsMultilingual object: { "tr": "…", "en": "…" }; chosen based on the recipient's language.
notification.imagebig_pictureAndroid big picture, iOS attachment (NSE), web chrome_web_image.
datadataString values only. On Android, Pushizo always sends data-only messages; the visible notification is built by the SDK (PushizoMessagingService), and your data field arrives in the click event as event.notification.data.
android.priority: HIGH / apns.headers.apns-priority: 10priority: 105 for normal.
android.ttl / apns-expirationttlSeconds.
android.collapse_key / apns-collapse-idcollapse_id
android.notification.channel_idandroid_channel_idChannel definitions: Dashboard → Settings → Android notification categories.
android.notification.icon / color / sound / visibilitysmall_icon / android_accent_color / android_sound / android_visibilityColor as AARRGGBB; visibility 1, 0, -1.
android.notification.tag (grouping)android_groupGroup + summary notification.
android.notification.click_action / webpush.fcm_options.linkurl / app_urlapp_url is a deep link.
apns.payload.aps.soundios_sound
apns.payload.aps.badgeios_badge_type: "SetTo" + ios_badge_count (or "Increase")
apns.payload.aps.categoryios_category
apns.payload.aps.thread-idthread_id
apns.payload.aps.interruption-levelios_interruption_levelpassive, active, time-sensitive, critical
apns.payload.aps.relevance-scoreios_relevance_score
apns.payload.aps.target-content-idtarget_content_identifier
apns.payload.aps.mutable-contentmutable_contentPushizo already sends 1 for visible notifications (NSE rich media + received).
apns.payload.aps.content-available (silent)content_available: trueAn hs_silent data message on Android, a background push on iOS.
apns.fcm_options.imagebig_picture or ios_attachments
webpush.notification.icon / image / badgechrome_web_icon / chrome_web_image / chrome_web_badge
webpush.notification.actionsweb_buttonsUp to 2 buttons.
webpush.notification.requireInteractionrequire_interaction
webpush.headers.Topicweb_push_topic
fcm_options.analytics_labelname, labelsVisible in the dashboard and reports.
android.direct_boot_ok, android.restricted_package_name—Not supported.

Example (Firebase Admin SDK → Pushizo Node SDK):

// Before (firebase-admin)
await admin.messaging().send({
  token,
  notification: { title: 'Your order has shipped', body: 'Tracking link inside', image: 'https://cdn.pushizo.com/box.png' },
  data: { order_id: '1001', screen: 'orders' },
  android: { priority: 'high', notification: { channelId: 'orders' } },
  apns: { payload: { aps: { sound: 'default', 'thread-id': 'orders' } } },
});

// After (@pushizo/node)
await hs.notifications.create({
  idempotency_key: 'order-1001-shipped',
  target: { include_external_ids: [userId] },           // a user instead of a token
  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.pushizo.com/box.png',
  data: { order_id: '1001', screen: 'orders' },
  priority: 10,
  android_channel_id: 'orders',
  ios_sound: 'default',
  thread_id: 'orders',
});

The same request is made with notifications.create in the Python/Go/Java/.NET/Ruby SDKs; in languages without a server SDK, use curl:

curl -X POST https://api.pushizo.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 (silent) messages

  • An FCM data-only message: in Pushizo, content_available: true + data. The Android SDK does not show a notification; on iOS it is sent with apns-push-type: background (aps.content-available: 1). Apple's limit of a few messages per hour applies to iOS background pushes.
  • Custom handling you do in FirebaseMessagingService.onMessageReceived moves to Pushizo.Notifications.addForegroundLifecycleListener (foreground) and addClickListener (click, event.notification.data) in Pushizo. If you keep your own FirebaseMessagingService class, only one service in the manifest receives FCM messages; Pushizo's PushizoMessagingService is added through manifest merging, so either remove your own service or check the data.hs_delivery_id field to tell non-Pushizo messages apart.

6. Analytics differences

MetricFirebasePushizo
SentFCM response (messageId)delivery.sent (provider_message_id), message counter counts.sent
Reached the deviceNone (only GA notification_receive, Android)received — reported by the Android SDK onMessageReceived, the iOS NSE and the web service worker (confirmed delivery)
OpenedGA notification_openopened (+ button_id), webhook delivery.opened
Failed / invalid tokenFCM error code; you clean up the tokendelivery.failed (error_code), subscription automatically set to invalid, subscription.invalidated webhook
ConversionGA conversion eventEvent definition is_conversion + attribution window (GET /v1/apps/{app_id}/analytics/conversions)
ReportsFirebase consoleDashboard → Analytics (delivery, subscription growth, event volume, funnel, retention, provider health) and GET /v1/apps/{app_id}/analytics/* (format=csv for CSV)
Raw event exportBigQuery exportPOST /v1/notifications/{id}/export_events, POST /v1/apps/{app_id}/exports (deliveries, events)

If you have dashboards built on Firebase Analytics events (notification_receive, notification_open), you can produce the same metrics by writing Pushizo webhooks (delivery.*) into your own data warehouse; events are deduplicated with Pushizo-Event-Id.

7. Migration order

  1. Set up and validate the channels; mark a test device as a Test device and check delivery with Messages → Send test push.
  2. Move sending to Pushizo on the server side (transactional notifications first, then bulk campaigns). Convert topic-based sends into segments.
  3. Add the Pushizo SDK to your Android/iOS apps (docs/sdk/android.md, docs/sdk/ios.md) and publish the new version; put the login(externalId) call into your authentication flow.
  4. For users on older versions (without the SDK), import tokens with Option B; as the new version rolls out, these records merge with the SDK registrations on (app, channel, token).
  5. Stop sending from the Firebase console/Admin SDK; keep the service account key only in Pushizo.

On this page