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
| Topic | Sending directly with FCM | Pushizo |
|---|---|---|
| Android transport | FCM | FCM (the same Firebase project, with the service account JSON) |
| iOS transport | FCM → APNs (requires the Firebase iOS SDK) | Direct APNs (.p8 key); no Firebase iOS SDK needed |
| Web transport | FCM web (Firebase VAPID key) | Standard Web Push, with a VAPID pair generated by Pushizo |
| Targeting | Token, topic, condition | User (external_id), subscription, segment (tag/property/event filters), alias |
| User model | None (you maintain your own token list) | User + multiple subscriptions; device merging (login) |
| Scheduling, quiet hours, frequency capping | In your own code | Platform features (send_after, delivery_time_of_day, app settings) |
| Analytics | Firebase Analytics events (notification_receive, notification_open) | Delivery timeline (queued → sent → received → opened), conversion attribution, webhook events |
| Email / SMS / in-app / notification inbox | None | Included |
2. Channel setup
Android (android_push)
- 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. - Dashboard → Channels → Android Push → upload the JSON → Validate (
POST /v1/apps/{app_id}/channels/android_push/validatemakes a test connection to FCM). The file is stored with envelope encryption and is never returned in any response. - With the API:
PUT /v1/apps/{app_id}/channels/android_push{ "provider": "fcm", "service_account": { …JSON object or file contents as text… } }(adminscope;confirm_project_change: trueif 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).
| Column | Value |
|---|---|
external_id | Your user ID (required if there is no token) |
channel | android_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. |
token | FCM registration token |
status | subscribed (default), unsubscribed, invalid |
language, timezone | tr, 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.csvWhen 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.
| FCM | Pushizo |
|---|---|
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 user | Categories (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 v1 | Pushizo | Note |
|---|---|---|
token / topic / condition | target.include_subscription_ids / target.include_external_ids / target.included_segments / target.filters | The target object is required. |
notification.title / notification.body | headings / contents | Multilingual object: { "tr": "…", "en": "…" }; chosen based on the recipient's language. |
notification.image | big_picture | Android big picture, iOS attachment (NSE), web chrome_web_image. |
data | data | String 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: 10 | priority: 10 | 5 for normal. |
android.ttl / apns-expiration | ttl | Seconds. |
android.collapse_key / apns-collapse-id | collapse_id | |
android.notification.channel_id | android_channel_id | Channel definitions: Dashboard → Settings → Android notification categories. |
android.notification.icon / color / sound / visibility | small_icon / android_accent_color / android_sound / android_visibility | Color as AARRGGBB; visibility 1, 0, -1. |
android.notification.tag (grouping) | android_group | Group + summary notification. |
android.notification.click_action / webpush.fcm_options.link | url / app_url | app_url is a deep link. |
apns.payload.aps.sound | ios_sound | |
apns.payload.aps.badge | ios_badge_type: "SetTo" + ios_badge_count (or "Increase") | |
apns.payload.aps.category | ios_category | |
apns.payload.aps.thread-id | thread_id | |
apns.payload.aps.interruption-level | ios_interruption_level | passive, active, time-sensitive, critical |
apns.payload.aps.relevance-score | ios_relevance_score | |
apns.payload.aps.target-content-id | target_content_identifier | |
apns.payload.aps.mutable-content | mutable_content | Pushizo already sends 1 for visible notifications (NSE rich media + received). |
apns.payload.aps.content-available (silent) | content_available: true | An hs_silent data message on Android, a background push on iOS. |
apns.fcm_options.image | big_picture or ios_attachments | |
webpush.notification.icon / image / badge | chrome_web_icon / chrome_web_image / chrome_web_badge | |
webpush.notification.actions | web_buttons | Up to 2 buttons. |
webpush.notification.requireInteraction | require_interaction | |
webpush.headers.Topic | web_push_topic | |
fcm_options.analytics_label | name, labels | Visible 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 withapns-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.onMessageReceivedmoves toPushizo.Notifications.addForegroundLifecycleListener(foreground) andaddClickListener(click,event.notification.data) in Pushizo. If you keep your ownFirebaseMessagingServiceclass, only one service in the manifest receives FCM messages; Pushizo'sPushizoMessagingServiceis added through manifest merging, so either remove your own service or check thedata.hs_delivery_idfield to tell non-Pushizo messages apart.
6. Analytics differences
| Metric | Firebase | Pushizo |
|---|---|---|
| Sent | FCM response (messageId) | delivery.sent (provider_message_id), message counter counts.sent |
| Reached the device | None (only GA notification_receive, Android) | received — reported by the Android SDK onMessageReceived, the iOS NSE and the web service worker (confirmed delivery) |
| Opened | GA notification_open | opened (+ button_id), webhook delivery.opened |
| Failed / invalid token | FCM error code; you clean up the token | delivery.failed (error_code), subscription automatically set to invalid, subscription.invalidated webhook |
| Conversion | GA conversion event | Event definition is_conversion + attribution window (GET /v1/apps/{app_id}/analytics/conversions) |
| Reports | Firebase console | Dashboard → Analytics (delivery, subscription growth, event volume, funnel, retention, provider health) and GET /v1/apps/{app_id}/analytics/* (format=csv for CSV) |
| Raw event export | BigQuery export | POST /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
- Set up and validate the channels; mark a test device as a Test device and check delivery with Messages → Send test push.
- Move sending to Pushizo on the server side (transactional notifications first, then bulk campaigns). Convert topic-based sends into segments.
- Add the Pushizo SDK to your Android/iOS apps (
docs/sdk/android.md,docs/sdk/ios.md) and publish the new version; put thelogin(externalId)call into your authentication flow. - 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). - Stop sending from the Firebase console/Admin SDK; keep the service account key only in Pushizo.
Migrating from your current platform to Pushizo
Pushizo deliberately preserves the legacy provider's concept model (app, subscription, user/alias, tag, segment, template, journey) and SDK surface (initialize → login → User.addTags → Notifications.requestPermission → Session.sendEvent)…
Changelog
Format: Keep a Changelog; versioning: semver. New changes are collected at the top under the [Unreleased] heading; before the version tag (vX.Y.Z), the heading is replaced with the version number and date (the release workflow…