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)…
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). This guide covers the steps for migrating an existing legacy provider integration without downtime, the field/endpoint mappings and the SDK changes.
Tools: npm run migrate:legacy (scripts/migrate-legacy.ts), the CSV importer (packages/db/src/data-transfer.ts → mapLegacyPlayerRow), the Postman collection (api/postman_collection.json).
1. Overall plan
| Step | Duration | Output |
|---|---|---|
| 1. Create the account, organization and app | 10 min | app_… ID |
2. Channel credentials (APNs .p8, FCM service account, VAPID, email/SMS) | 30 min | Channels active |
3. Player/subscription migration (migrate:legacy → CSV → import) | depends on file size | Users, tags, iOS/Android/email/SMS subscriptions |
| 4. Server integration (REST → Pushizo public API / server SDKs) | 1–3 days | Notification, user and event calls |
| 5. Client SDK replacement (Web/iOS/Android/Flutter, React Native/Capacitor/Cordova/.NET MAUI/Unity) | 1–2 days | New version release |
| 6. Dual-write period and cutover | 2–4 weeks | The legacy provider is shut down |
2. Creating an account and app
- Sign up in the dashboard (
/register) and complete email verification and optional MFA. Every account works under an organization; the organization corresponds to the legacy provider's "account", and an app corresponds to a legacy provider app. - Create the app with the Getting started wizard (
/<org>/getting-started) or through the public API:POST /v1/apps(requires an org-wideadminkey). - Generate a server key (
hs_live_…) under Organization → API keys. Scopes are more granular than the legacy provider's REST API key:notifications:write,users:read,users:write,events:write,segments:read,analytics:read,admin. For the migration, anadmin-scoped key with an IP allowlist and an expiry date is recommended. - On the Channels page, enter the same credentials you used with the legacy provider:
| Legacy provider setting | Pushizo channel | Notes |
|---|---|---|
Apple → .p8 key, Key ID, Team ID, Bundle ID | iOS Push (ios_push) | Environment sandbox / production; the same .p8 works on both sides. |
| Google → Firebase service account JSON | Android Push (android_push) | The same Firebase project is used; device tokens remain valid. |
| Web → Safari/Chrome settings | Web Push (web_push) | Pushizo generates its own VAPID pair; existing browser subscriptions cannot be migrated (see §4.3). |
| Email (SendGrid, etc.) | Email (email) | SMTP / Amazon SES / Resend; re-verify the sender domain (SPF/DKIM/DMARC). |
| SMS (Twilio) | SMS (sms) | The same Twilio account details; Netgsm is also supported. |
On each channel, the Validate button (POST /v1/apps/{app_id}/channels/{channel}/validate) makes a test connection to the provider.
3. Player (subscription) migration
3.1 npm run migrate:legacy
The tool pulls devices from the legacy provider's "View devices" API (GET /players, pages of 300) or, for large apps, with POST /players/csv_export, writes them in Pushizo's legacy_players CSV format and, if requested, starts the import directly and monitors it until it completes.
# Generate the CSV only
npm run migrate:legacy -- --source-app-id <SOURCE_APP_ID> --source-key <REST_API_KEY> --out players.csv
# Large app: use the legacy provider's csv_export (gz)
npm run migrate:legacy -- --source-app-id <id> --source-key <key> --csv-export --out players.csv
# Generate the CSV and import it into Pushizo (waits until the job completes)
npm run migrate:legacy -- --source-app-id <id> --source-key <key> \
--hs-api-url https://api.pushizo.com --hs-api-key hs_live_… --hs-app-id app_…Environment variables are also accepted: SOURCE_APP_ID, SOURCE_REST_API_KEY, HS_API_URL, HS_API_KEY, HS_APP_ID. Output is written to stdout as JSON: { players, file, importId, importStatus, stats }.
The CSV headers are the same as the legacy provider's export format (id, identifier, session_count, language, timezone, game_version, device_os, device_type, device_model, ad_id, tags, last_active, playtime, amount_spent, created_at, invalid_identifier, badge_count, external_user_id, notification_types). You can also upload the "Export" file you downloaded from the legacy provider's dashboard directly, without using the tool.
3.2 Importing the CSV manually
curl -X POST "https://api.pushizo.com/v1/apps/app_…/imports" \
-H "Authorization: Bearer hs_live_…" \
-F type=legacy_players -F file=@players.csv
# → { "id": "imp_…", "status": "queued" }
curl "https://api.pushizo.com/v1/apps/app_…/imports/imp_…" -H "Authorization: Bearer hs_live_…"
# → { "status": "completed", "stats": { "processed", "created_users", "updated_users", "created_subscriptions", "skipped", "errors" }, "error_report_url": "…" }Dashboard equivalent: Audience → Export / Import. The file limit is 50 MB and 500,000 rows; split larger files. Imports are idempotent: uploading the same file a second time does not duplicate users or subscriptions.
3.3 Field mapping table (mapLegacyPlayerRow)
| Legacy provider column | Pushizo field | Rule |
|---|---|---|
external_user_id | external_id | If empty and identifier is present, an anonymous user is created; if both are empty, the row goes to the error report. |
identifier | subscription token | Push token / email / phone. Emails are lowercased and phone numbers normalized to E.164; invalid values cause the row to be skipped. |
device_type | subscription channel | 0 → ios_push; 1, 2, 13 → android_push; 11 → email; 14 → sms; 5, 7, 8, 9, 10 (web) → only the user is created (see below). Other values: no subscription. |
invalid_identifier = t | subscription status: invalid | |
notification_types < 0 | subscription status: unsubscribed | Otherwise subscribed. |
tags (JSON) | user tags | Values are converted to strings (objects/arrays become JSON text, null is skipped). Invalid JSON → row error. |
language | properties.language, device.locale | |
timezone (seconds from UTC) | device.timezone | Etc/GMT∓h if it is a whole hour (UTC+3 → Etc/GMT-3), otherwise empty. |
device_model, device_os, game_version | device.model, device.os_version, device.app_version | |
session_count, created_at, last_active | session_count, first_seen_at, last_active_at | |
id, ad_id, playtime, amount_spent, badge_count | — | Not imported. |
Web push subscriptions cannot be migrated via CSV: the legacy provider's export does not include the p256dh/auth keys, and because the VAPID key pair changes, browser subscriptions must be recreated. When the Pushizo Web SDK loads (with the default autoResubscribe: true), web visitors who have already granted permission re-subscribe silently; that's why you should keep the dual-write period long for web.
3.4 Post-migration checks
- On the Subscriptions page, compare the channel distribution with the legacy provider's "Audience" counts.
- Mark a device as a Test device and verify real delivery with Messages → Send test push (APNs/FCM tokens from the legacy provider also work from Pushizo).
- Review the rows in the
error_report_urlfile (line, error, row).
4. API mapping table
Authentication: legacy provider Authorization: Basic <REST_API_KEY> → Pushizo Authorization: Bearer hs_live_…. Error envelope: { "error": { "code": "HS_…", "message", "details", "request_id" } } (error catalog). Pagination uses cursor/limit (next_cursor, has_more) instead of the legacy provider's offset/limit.
4.1 Endpoints
| Legacy provider REST | Pushizo public API | Difference |
|---|---|---|
POST /notifications | POST /v1/notifications | app_id in the body; response 202 { id, status, recipients_estimate }. For idempotency, use the Idempotency-Key header or the idempotency_key field (legacy provider external_id). |
GET /notifications?app_id= | GET /v1/notifications?app_id= | Cursor pagination, status filter. |
GET /notifications/{id} | GET /v1/notifications/{message_id} | counts object (queued, sent, delivered, failed, opened, clicked, suppressed…). |
DELETE /notifications/{id} | DELETE /v1/notifications/{message_id} | Only scheduled/queued messages can be canceled. |
GET /notifications/{id}/history | GET /v1/notifications/{message_id}/history | CSV job; download_url when complete. |
POST /notifications/{id}/export_events | POST /v1/notifications/{message_id}/export_events | CSV job; download_url. |
GET /players (view devices) | GET /v1/apps/{app_id}/users + GET /v1/apps/{app_id}/subscriptions/{id} | Users and subscriptions instead of the device concept; the subscription's owner via GET …/subscriptions/{id}/user/identity. |
GET /players/{id} | GET /v1/apps/{app_id}/subscriptions/{subscription_id} | Fields: channel, status, token_masked, device, user_id. |
POST /players / PUT /players/{id} | POST /v1/apps/{app_id}/users (with subscriptions) / PATCH …/subscriptions/{id} | For server-side device registration, use users.upsert + subscriptions[]. |
PUT /players/{id} (tag update) | PATCH /v1/apps/{app_id}/users/by/{label}/{value} | Merge-patch of tags, properties, deltas. A null value deletes the tag. |
POST /players/csv_export | POST /v1/apps/{app_id}/exports (type: users | subscriptions | events | deliveries) | GET …/exports/{id} → download_url. |
GET /users/by/{alias_label}/{alias_id} | GET /v1/apps/{app_id}/users/by/{label}/{value} | Same path; hs_id corresponds to the legacy provider's own user ID. |
POST /users | POST /v1/apps/{app_id}/users | external_id, tags, properties, language, subscriptions[]. |
PATCH /users/by/{label}/{value} | PATCH /v1/apps/{app_id}/users/by/{label}/{value} | |
DELETE /users/by/{label}/{value} | DELETE /v1/apps/{app_id}/users/by/{label}/{value} | Subscriptions are deleted and events anonymized. |
GET/PATCH /users/by/{label}/{value}/identity | GET/PATCH /v1/apps/{app_id}/users/by/{label}/{value}/identity | Adds aliases; DELETE …/identity/{alias_label} removes one. |
POST /users/by/{label}/{value}/subscriptions | POST /v1/apps/{app_id}/users/by/{label}/{value}/subscriptions | { channel, token, device? }. |
PATCH /subscriptions/{id} | PATCH /v1/apps/{app_id}/subscriptions/{subscription_id} | opted_in, device, test_device. |
DELETE /subscriptions/{id} | DELETE /v1/apps/{app_id}/subscriptions/{subscription_id} | |
PATCH /subscriptions_by_token/{token_type}/{token} | PATCH /v1/apps/{app_id}/subscriptions_by_token/{token_type}/{token} | The legacy provider's type names (iOSPush, AndroidPush, ChromePush, FirefoxPush, SafariPush, Email, SMS) are also accepted. |
POST /subscriptions/{id}/owner | POST /v1/apps/{app_id}/subscriptions/{subscription_id}/owner | { external_id }. |
GET /subscriptions/{id}/user/identity | GET /v1/apps/{app_id}/subscriptions/{subscription_id}/user/identity | |
POST /apps/{app_id}/custom_events | POST /v1/apps/{app_id}/events | [{ external_id | subscription_id, name, properties, value, occurred_at }], up to 500. |
GET /apps/{app_id}/outcomes | GET /v1/apps/{app_id}/analytics/conversions | A conversion event is marked with event_definitions.is_conversion (PATCH …/events/definitions/{name}). |
GET/POST /apps/{app_id}/segments, DELETE …/segments/{id} | GET/POST /v1/apps/{app_id}/segments, PATCH/DELETE …/{id} | Filter AST ({ field, op, value } conditions, all/any/none groups; e.g. tags.plan, properties.city, language, event); POST …/segments/preview returns a count + sample users. |
GET/POST /templates | GET/POST /v1/apps/{app_id}/templates, PATCH/DELETE …/{id}, POST …/{id}/render | Liquid; version history via …/versions, copy to another app via …/copy_to_app. |
GET /apps, GET /apps/{id} | GET /v1/apps, GET /v1/apps/{app_id} | PATCH /v1/apps/{app_id} updates settings. |
POST /apps | POST /v1/apps | Org-wide admin key. |
| Automations (dashboard only) | GET/POST /v1/apps/{app_id}/journeys, …/draft, …/publish, …/runs | Can be designed and triggered through the API (journeys). |
| In-App Messages (dashboard only) | GET/POST /v1/apps/{app_id}/in-app-messages | Block-based, HTML (HTML in-app) and carousel; mobile and web. |
Live Activities: POST /apps/{app_id}/activities/activity/{activity_type} (push-to-start), POST /apps/{app_id}/live_activities/{activity_id}/notifications (update/end) | POST /v1/apps/{app_id}/live-activities/{activity_type}/start, …/update, …/end; type registrations via …/live-activities/types | There is also a journey node (Live Activities). |
The Postman collection (api/postman_collection.json) includes all of these endpoints with the {{baseUrl}}, {{apiKey}} and {{appId}} variables.
4.2 POST /notifications body
In Pushizo, targeting fields are grouped under the target object; most content fields keep the same name.
| Legacy provider | Pushizo | Note |
|---|---|---|
included_segments / excluded_segments | target.included_segments / target.excluded_segments | Segment IDs (seg_…) or names. |
include_aliases: { external_id: [] } | target.include_aliases or target.include_external_ids | Up to 2000. |
include_subscription_ids (formerly include_player_ids) | target.include_subscription_ids | |
include_email_tokens | target.email_to | For an address without a subscription, an anonymous user + subscription is created. |
include_phone_numbers | target.include_phone_numbers | E.164. |
filters | target.filters | Segment AST ({ field: "tags.plan", op: "eq", value: "pro" } and all/any/none groups instead of the legacy provider's field/relation/value). |
target_channel: "push" | "email" | "sms" | target.channels: ["ios_push", "android_push", "web_push", "email", "sms"] | Inferred from the content if not given; SMS only when explicit. |
isIos, isAndroid, isAnyWeb | target.channels | |
headings, contents, subtitle, url, app_url, data, buttons, big_picture, ios_attachments, ios_sound, ios_category, thread_id, ios_relevance_score, target_content_identifier, android_channel_id, android_group, android_sound, small_icon, large_icon, android_accent_color, android_visibility, chrome_web_icon, chrome_web_image, chrome_web_badge, web_push_topic, web_buttons, content_available, mutable_content, template_id, custom_data, send_after, delayed_option, delivery_time_of_day, ttl, priority, collapse_id, email_subject, email_body, email_preheader, email_from_name, email_from_address, email_reply_to_address, disable_email_click_tracking, sms_from, sms_media_urls, include_unsubscribed, name | same name | priority is 5 (normal) or 10 (high), as with the legacy provider; ttl is in seconds. |
ios_badgeType, ios_badgeCount | ios_badge_type, ios_badge_count | snake_case. |
ios_interruption_level | ios_interruption_level | passive, active, time-sensitive, critical (critical alert guide). |
external_id (idempotency) | idempotency_key or the Idempotency-Key header | The same key + the same body returns the same response; a different body returns 409 HS_IDEMPOTENCY_CONFLICT. |
send_after + delayed_option: "timezone" | same | delivery_time_of_day: "09:00". |
throttle_rate_per_minute | throttle_rate_per_minute | |
email_mjml | email_mjml | Not available in the legacy provider; MJML compilation is specific to Pushizo. |
| — | add_to_inbox, inbox_ttl, category, labels, one_per_user, frequency_cap_exempt, quiet_hours_exempt, require_interaction | Additional Pushizo fields. |
Example (Node server SDK):
import { Pushizo } from '@pushizo/node';
const hs = new Pushizo({ apiKey: process.env.HS_API_KEY!, appId: process.env.HS_APP_ID, baseUrl: 'https://api.pushizo.com' });
await hs.notifications.create({
idempotency_key: `order-${order.id}`,
target: { include_aliases: { external_id: [userId] } },
headings: { tr: 'Siparişiniz yola çıktı', en: 'Your order has shipped' },
contents: { tr: 'Kargo takip bağlantısı içeride', en: 'Tracking link inside' },
url: `https://pushizo.com/orders/${order.id}`,
data: { order_id: order.id },
});4.3 Webhooks
The equivalent of the legacy provider's "Event Streams" is Pushizo's webhook endpoints (/v1/apps/{app_id}/webhooks) and the body template/event filter of the same name, Event Streams (Event Streams); events are HMAC-signed (Pushizo-Signature: t=…,v1=…): delivery.*, subscription.*, user.*, event.received, conversion.created, campaign.*, journey.*, in_app.*. For signature verification and the retry schedule, see webhooks.
5. SDK migration guide
None of the client SDKs use a secret key; only the App ID (and your own API address) is used. If identity verification is required, login takes the proof generated by your server as its second parameter: an ES256 JWT (jwt mode), as with the legacy provider, or identity_hash = HMAC-SHA256(sdk_secret, external_id) (hash mode); details in identity verification with JWT. Unlike the legacy provider, the web SDK is also supported.
5.1 Web
| Legacy provider v16 (Web) | Pushizo Web SDK (@pushizo/web) |
|---|---|
<script src="legacy web SDK script"> + legacy SDK init call | <script src="https://api.pushizo.com/sdk-web/PushizoSDK.js" async> + PushizoDeferred.push(async (Pushizo) => { await Pushizo.init({ appId: 'app_…', apiUrl: 'https://api.pushizo.com' }) }) |
LegacySDKWorker.js at the site root | PushizoSDKWorker.js at the site root (importScripts(apiUrl + '/sdk-web/PushizoSDKWorker.js')); the serviceWorkerPath / serviceWorkerScope options mean the same thing |
LegacySDK.login(externalId, jwtToken?) | Pushizo.login(externalId, identityHash?) |
LegacySDK.logout() | Pushizo.logout() |
LegacySDK.User.addTag / addTags / removeTag / removeTags / getTags | same names: Pushizo.User.addTag / addTags / removeTag / removeTags / getTags |
LegacySDK.User.addAlias / addAliases / removeAlias | same names |
LegacySDK.User.addEmail / removeEmail / addSms / removeSms | same names (addresses are normalized on the client) |
LegacySDK.User.setLanguage | Pushizo.User.setLanguage |
LegacySDK.User.PushSubscription.optIn / optOut / id / token / optedIn + addEventListener('change') | Pushizo.User.pushSubscription.optIn / optOut / id / optedIn / state + addObserver(cb) (the returned function removes the listener) |
LegacySDK.Notifications.requestPermission() / permission | Pushizo.Notifications.requestPermission() / permission ('default' | 'granted' | 'denied' | 'unsupported') |
LegacySDK.Notifications.addEventListener('click', cb) | Pushizo.Notifications.addClickListener(({ notification, result }) => …) |
LegacySDK.Notifications.addEventListener('foregroundWillDisplay', cb) | Pushizo.Notifications.addForegroundLifecycleListener((e) => e.preventDefault()) |
LegacySDK.Slidedown.promptPush / promptEmail / promptSms / promptPushCategories | Pushizo.Slidedown.promptPush / promptEmail / promptSms / promptEmailAndSms (User.setPreferences for category preferences) |
promptOptions.slidedown, welcomeNotification, notificationClickHandlerMatch/Action, notifyButton | slidedown, welcomeNotification, notificationClickHandlerMatch / notificationClickHandlerAction, bell (init options) |
LegacySDK.Session.sendOutcome / sendUniqueOutcome / sendOutcomeWithValue | Pushizo.Session.sendEvent(name, properties?, value?) |
LegacySDK.User.PushSubscription no notification inbox | Pushizo.Inbox.list / markRead / markAllRead / archive / unreadCount / addObserver |
| In-app (mobile only) | Pushizo.InAppMessages.addTrigger / addTriggers / removeTrigger / clearTriggers / setScreen / paused / addClickListener / addLifecycleListener (including web) |
LegacySDK.setConsentRequired(true) + setConsentGiven(true) | init({ requiresPrivacyConsent: true }) + Pushizo.setConsentGiven(true) |
LegacySDK.Debug.setLogLevel | Pushizo.Debug.setLogLevel('debug') |
Details: Web SDK; framework integrations: React, Vue, Angular; iOS Safari PWA: iOS web push.
5.2 iOS
| Legacy provider iOS SDK 5 | Pushizo iOS SDK (Pushizo, PushizoExtension) |
|---|---|
LegacySDK.initialize("APP_ID", withLaunchOptions:) | Pushizo.initialize("app_…", launchOptions:) { options in options.apiUrl = "https://api.pushizo.com" } |
| Token via swizzling | No swizzling: Pushizo.setDeviceToken(deviceToken) in didRegisterForRemoteNotificationsWithDeviceToken, and Pushizo.setDeviceTokenError(error) on failure |
LegacySDK.login("id") / logout() | Pushizo.login("id", identityHash: nil) / Pushizo.logout() |
LegacySDK.User.addTag/addTags/removeTag/getTags/setLanguage | same names |
LegacySDK.User.addEmail/addSms/removeEmail/removeSms | same names |
LegacySDK.User.pushSubscription.optIn()/optOut()/id/token/optedIn + addObserver | Pushizo.User.pushSubscription.optIn()/optOut()/id/token, await state(), addObserver { state in } |
LegacySDK.Notifications.requestPermission(_:fallbackToSettings:) | Pushizo.Notifications.requestPermission { granted in } (read with await permission()) |
LegacySDK.Notifications.addPermissionObserver | addPermissionObserver { granted in } → HSListenerToken; removePermissionObserver(token) |
addClickListener / addForegroundLifecycleListener | same names; they return a token (removeClickListener(token)) |
LegacyNotificationServiceExtension | PushizoNotificationServiceExtension(appId:apiUrl:appGroup:) → didReceive, serviceExtensionTimeWillExpire |
LegacySDK.InAppMessages.addTrigger/removeTrigger/clearTriggers/paused | same names + setScreen, addClickListener, addLifecycleListener |
LegacySDK.Session.sendOutcome(_:) | Pushizo.Session.sendEvent("name", properties:, value:) |
LegacySDK.setConsentRequired/setConsentGiven | options.requiresPrivacyConsent = true + Pushizo.setConsentGiven(true) |
LegacySDK.Notifications.clearAll() | Pushizo.Notifications.clearAll(), removeGroupedNotifications, removeNotification(identifier:) |
| Live Activities | Pushizo.LiveActivities.register(DeliveryAttributes.self) (iOS 16.1+; push-to-start 17.2+). Details: iOS SDK. |
Because the same APNs .p8 key is used, existing device tokens also receive deliveries from Pushizo; on first launch the SDK registers the token with POST /subscriptions (it merges with the migrated subscription on (app, channel, token)). Details: iOS SDK.
5.3 Android
| Legacy provider Android SDK 5 | Pushizo Android SDK (com.pushizo:pushizo-android) |
|---|---|
LegacySDK.initWithContext(this, "APP_ID") | Pushizo.initialize(this, "app_…", Pushizo.Options(apiUrl = "https://api.pushizo.com")) (in Application onCreate) |
LegacySDK.login("id") / logout() | Pushizo.login("id", identityHash = null) / Pushizo.logout() |
LegacySDK.User.addTag/addTags/removeTag/getTags/setLanguage | same names |
LegacySDK.User.addEmail/addSms/removeEmail/removeSms | same names (emails, smsNumbers lists) |
LegacySDK.User.pushSubscription.optIn()/optOut()/id/token/optedIn + addObserver | same names (plus state) |
LegacySDK.Notifications.requestPermission(fallbackToSettings) (coroutine) | Pushizo.Notifications.requestPermission(activity) + Pushizo.Notifications.onPermissionResult() in onRequestPermissionsResult (PERMISSION_REQUEST_CODE) |
addPermissionObserver | addPermissionObserver(observer) / removePermissionObserver(observer) |
addClickListener / addForegroundLifecycleListener | same names |
LegacySDK.InAppMessages.addTrigger/…/paused | same names + setScreen, addClickListener, addLifecycleListener |
LegacySDK.Session.sendOutcome | Pushizo.Session.sendEvent("name", mapOf(...), value) |
LegacySDK.consentRequired = true / consentGiven = true | Options(requiresPrivacyConsent = true) + Pushizo.setConsentGiven(true) |
LegacySDK.Notifications.clearAllNotifications() | Pushizo.Notifications.clearAll(), removeNotification, removeGroupedNotifications |
| Notification channels (from the dashboard) | Dashboard → Settings → Android notification categories (android_channels); selected with android_channel_id |
As long as the same Firebase project is used, FCM tokens do not change. Details: Android SDK.
5.4 Flutter
legacy Flutter package | pushizo_flutter |
|---|---|
LegacySDK.initialize("APP_ID") | await Pushizo.initialize('app_…', apiUrl: 'https://api.pushizo.com') |
LegacySDK.login/logout | Pushizo.login(externalId, identityHash: null) / Pushizo.logout() |
LegacySDK.User.addTags/removeTag/getTags/setLanguage | same names (all return a Future) |
LegacySDK.User.addEmail/addSms/removeEmail/removeSms | same names |
LegacySDK.User.pushSubscription.optIn/optOut/id/token/optedIn + addObserver | Pushizo.User.pushSubscription.optIn()/optOut(), await state, changes.listen(...) |
LegacySDK.Notifications.requestPermission(true) | await Pushizo.Notifications.requestPermission() |
LegacySDK.Notifications.addPermissionObserver | Pushizo.Notifications.addPermissionObserver(fn) or permissionStream.listen(...) |
addClickListener / addForegroundWillDisplayListener | Pushizo.Notifications.clickStream.listen(...) / foregroundStream.listen(...) |
LegacySDK.InAppMessages.addTrigger/…/paused(bool) | same names + setScreen, setPaused(bool), clickStream, lifecycleStream, setNavigatorKey |
LegacySDK.Session.sendOutcome | Pushizo.Session.sendEvent(name, properties:, value:) |
LegacySDK.consentRequired(true) / consentGiven(true) | initialize(..., requiresPrivacyConsent: true) + Pushizo.setConsentGiven(true) |
| — | Pushizo.Inbox.list/markRead/markAllRead/archive/unreadCount, Pushizo.User.getPreferences/setPreferences |
Details: Flutter SDK.
5.5 Common notes for bridge SDKs
In the tables below, the legacy provider column is based on the v5 API names of the respective package; if you are moving from an older (v3/v4) legacy provider version, first map your calls to their v5 equivalents. In all bridge SDKs:
- The package swap happens in one go: remove the legacy provider package (and, for Expo, the
legacy Expo plugin), add the Pushizo package and regenerate the native project (pod install,npx cap sync,cordova prepare,expo prebuild). Because Pushizo takes over theUNUserNotificationCenterdelegate on iOS, two push SDKs must not coexist in the same release. initializetakes your own API address (apiUrl) alongside the App ID; no REST API key is embedded in the client.- The legacy provider's "outcome" calls (
addOutcome,addUniqueOutcome,addOutcomeWithValueand their C# equivalents) become a singleSession.sendEvent(name, properties?, value?)call; the same name also fires in-appeventtriggers. If you need uniqueness, enforce it in the app or in a journey/segment condition. - The notification inbox (
Inbox) and category preferences (User.getPreferences/setPreferences) are additions with no equivalent in the legacy provider (see 5.11).
5.6 React Native
legacy React Native package 5 | @pushizo/react-native |
|---|---|
Expo: ["legacy Expo plugin", { "mode": "development" }] | ["@pushizo/react-native", { "mode": "development", "appId": "app_…" }] (the plugin is included in the package; the NSE target is PushizoNotificationServiceExtension) |
| Bare iOS: token obtained via swizzling | No swizzling: Pushizo.setDeviceToken(deviceToken) / Pushizo.setDeviceTokenError(error) in AppDelegate (the Expo plugin adds this automatically) |
LegacySDK.initialize('APP_ID') | await Pushizo.initialize('app_…', { apiUrl: 'https://api.pushizo.com' }) |
LegacySDK.login(externalId) / LegacySDK.logout() | Pushizo.login(externalId, identityHash?) / Pushizo.logout() |
LegacySDK.User.addTag / addTags / removeTag / removeTags / getTags | same names |
LegacySDK.User.addAlias / addAliases / removeAlias | same names |
LegacySDK.User.addEmail / removeEmail / addSms / removeSms, setLanguage | same names |
LegacySDK.User.getExternalId() / getLegacyId() | Pushizo.User.getExternalId() / getPushizoId() |
LegacySDK.User.pushSubscription.getIdAsync / getTokenAsync / getOptedInAsync / optIn / optOut + addEventListener('change', …) | same names ({ previous, current }) |
LegacySDK.Notifications.requestPermission(fallbackToSettings) | Pushizo.Notifications.requestPermission() |
LegacySDK.Notifications.getPermissionAsync() | Pushizo.Notifications.getPermissionAsync() (latest value synchronously: permission) |
LegacySDK.Notifications.addEventListener('click' | 'foregroundWillDisplay' | 'permissionChange', …) | same event names; e.preventDefault() and e.getNotification().display() work the same |
LegacySDK.Notifications.clearAll() | Pushizo.Notifications.clearAll() |
LegacySDK.InAppMessages.addTrigger / addTriggers / removeTrigger / removeTriggers / clearTriggers / setPaused / getPaused | same names + getTriggers, setScreen |
LegacySDK.InAppMessages.addEventListener('click' | 'willDisplay' | 'didDisplay' | 'willDismiss' | 'didDismiss', …) | same event names; event payload { messageId, actionId, url } / { messageId } |
LegacySDK.Session.addOutcome / addUniqueOutcome / addOutcomeWithValue | Pushizo.Session.sendEvent(name, properties?, value?) |
LegacySDK.setConsentRequired(true) + setConsentGiven(true) | initialize(…, { requiresPrivacyConsent: true }) + Pushizo.setConsentGiven(true) |
LegacySDK.Debug.setLogLevel(LogLevel.Verbose) | Pushizo.Debug.setLogLevel(LogLevel.Debug) |
| — | Pushizo.Inbox.*, Pushizo.User.getPreferences / setPreferences |
Details: React Native SDK.
5.7 Capacitor (Ionic)
In Ionic/Capacitor apps, the legacy provider uses the legacy Cordova plugin package; Pushizo has a separate Capacitor plugin (which delegates to @pushizo/web on the web).
legacy Cordova plugin 5 (Capacitor) | @pushizo/capacitor |
|---|---|
npm install legacy Cordova plugin | npm install @pushizo/capacitor (+ @pushizo/web for web), npx cap sync |
| iOS token obtained via swizzling | Post the capacitorDidRegisterForRemoteNotifications / capacitorDidFailToRegisterForRemoteNotifications notifications in AppDelegate.swift |
LegacySDK.initialize('APP_ID') | await Pushizo.initialize('app_…', { apiUrl: 'https://api.pushizo.com' }) |
LegacySDK.login / logout | Pushizo.login(externalId, identityHash?) / Pushizo.logout() (Promise) |
LegacySDK.User.addTag / addTags / removeTag / removeTags / getTags, addAlias / addAliases / removeAlias, addEmail / removeEmail / addSms / removeSms, setLanguage | same names (all return a Promise) |
LegacySDK.User.pushSubscription.getIdAsync / getTokenAsync / getOptedInAsync / optIn / optOut | Pushizo.User.pushSubscription.getId / getToken / getOptedIn / getState / optIn / optOut |
LegacySDK.User.pushSubscription.addEventListener('change', cb) | Pushizo.User.pushSubscription.addObserver((state) => …) (the returned function removes the subscription) |
LegacySDK.Notifications.requestPermission(true) | await Pushizo.Notifications.requestPermission() |
LegacySDK.Notifications.addEventListener('click', cb) | Pushizo.Notifications.addClickListener(({ notification, result }) => …) |
LegacySDK.Notifications.addEventListener('foregroundWillDisplay', cb) | Pushizo.Notifications.addForegroundLifecycleListener((e) => e.preventDefault()); to defer and then show it, await e.display() |
LegacySDK.Notifications.addEventListener('permissionChange', cb) | Pushizo.Notifications.addPermissionObserver(({ permission }) => …) |
LegacySDK.Notifications.clearAll() | Pushizo.Notifications.clearAll(), removeGroupedNotifications, removeNotification (Android only) |
LegacySDK.InAppMessages.addTrigger / addTriggers / removeTrigger / removeTriggers / clearTriggers / setPaused / getPaused | same names + getTriggers, setScreen |
LegacySDK.InAppMessages.addEventListener('click' | 'willDisplay' | …, cb) | Pushizo.InAppMessages.addClickListener(cb) / addLifecycleListener({ willDisplay, didDisplay, willDismiss, didDismiss }) |
LegacySDK.Session.addOutcome / addUniqueOutcome / addOutcomeWithValue | Pushizo.Session.sendEvent(name, properties?, value?) |
LegacySDK.setConsentRequired(true) + setConsentGiven(true) | initialize(…, { requiresPrivacyConsent: true }) + await Pushizo.setConsentGiven(true) |
LegacySDK.Debug.setLogLevel(…) | await Pushizo.Debug.setLogLevel('debug') |
Details: Capacitor SDK.
5.8 Cordova
legacy Cordova plugin 5 | cordova-plugin-pushizo |
|---|---|
cordova plugin add legacy Cordova plugin, window.plugins.LegacySDK | cordova plugin add cordova-plugin-pushizo, window.Pushizo (and window.plugins.Pushizo) |
| No Android Gradle setting required | config.xml → GradlePluginKotlinEnabled and GradlePluginGoogleServicesEnabled (the bridge is written in Kotlin) |
LegacySDK.initialize('APP_ID') (inside deviceready) | await Pushizo.initialize('app_…', { apiUrl: 'https://api.pushizo.com' }) |
| All other calls | Identical to the Capacitor table (5.7); all methods return a Promise, and errors are PushizoError (code) |
On iOS, the plugin adds the APNs token callbacks to the AppDelegate at runtime; no extra code is needed. Details: Cordova SDK.
5.9 .NET MAUI
LegacySDK.DotNet 5 | Pushizo.Maui |
|---|---|
dotnet add package LegacySDK.DotNet, using LegacySDK.DotNet; | dotnet add package Pushizo.Maui, using PushizoSdk.Maui; |
LegacySDK.Initialize("APP_ID") | builder.UsePushizo("app_…", o => o.ApiUrl = "https://api.pushizo.com") (MauiProgram.cs) or Pushizo.Initialize("app_…", options) |
| iOS token obtained via swizzling | PushizoIos.RegisteredForRemoteNotifications(deviceToken) / FailedToRegisterForRemoteNotifications(error) in AppDelegate |
LegacySDK.Login("id") / LegacySDK.Logout() | Pushizo.Login("id", identityHash) / Pushizo.Logout() |
LegacySDK.User.AddTag / AddTags / RemoveTag / RemoveTags, AddAlias / AddAliases / RemoveAlias, AddEmail / RemoveEmail / AddSms / RemoveSms | same names + GetTags(), SetLanguage("tr") |
LegacySDK.User.PushSubscription.OptIn() / OptOut() / Id / Token / OptedIn + Changed | same names (e.Previous, e.Current) |
await LegacySDK.Notifications.RequestPermissionAsync(true) | await Pushizo.Notifications.RequestPermissionAsync(fallbackToSettings: true) |
LegacySDK.Notifications.Clicked / ForegroundWillDisplay / PermissionChanged | same event names (EventHandler); e.Notification, e.ActionId, e.Url on click; e.PreventDefault() in the foreground |
LegacySDK.Notifications.ClearAllNotifications() | Pushizo.Notifications.ClearAll() |
LegacySDK.InAppMessages.AddTrigger / AddTriggers / RemoveTrigger / RemoveTriggers / ClearTriggers / Paused + Clicked / WillDisplay / DidDisplay / WillDismiss / DidDismiss | same names + GetTriggers(), SetScreen(name) |
LegacySDK.Session.AddOutcome / AddUniqueOutcome / AddOutcomeWithValue | Pushizo.Session.SendEvent(name, properties, value) |
LegacySDK.ConsentRequired = true + LegacySDK.ConsentGiven = true | o.RequiresPrivacyConsent = true + Pushizo.SetConsentGiven(true) |
LegacySDK.Debug.LogLevel = … | Pushizo.Debug.SetLogLevel(LogLevel.Debug) |
| — | Pushizo.Inbox.ListAsync / MarkReadAsync / MarkAllReadAsync / ArchiveAsync / UnreadCountAsync, Pushizo.User.GetPreferencesAsync / SetPreferencesAsync |
Details: .NET MAUI SDK.
5.10 Unity
| Legacy provider Unity SDK 5 | com.pushizo.unity |
|---|---|
Legacy provider UPM packages, using LegacySDK; | UPM package via Git URL (https://github.com/pushizo/pushizo-unity.git#0.1.0), using PushizoSdk;; Project Settings → Pushizo (App ID, App Group, google-services.json path) |
LegacySDK.Initialize("APP_ID") | Pushizo.Initialize("app_…", new PushizoOptions { ApiUrl = "https://api.pushizo.com" }) |
LegacySDK.Login("id") / LegacySDK.Logout() | Pushizo.Login("id", identityHash) / Pushizo.Logout() |
LegacySDK.User.AddTag / AddTags / RemoveTag / RemoveTags, AddAlias / AddAliases / RemoveAlias, AddEmail / RemoveEmail / AddSms / RemoveSms | same names + GetTags(), SetLanguage("tr") |
LegacySDK.User.PushSubscription.OptIn() / OptOut() / Id / Token / OptedIn + Changed | same names |
await LegacySDK.Notifications.RequestPermissionAsync(true) | await Pushizo.Notifications.RequestPermissionAsync(fallbackToSettings: true) |
LegacySDK.Notifications.Clicked / ForegroundWillDisplay / PermissionChanged += (sender, e) => … | same event names with an Action<T> signature: Clicked += e => …, PermissionChanged += granted => … (events arrive on the main thread) |
LegacySDK.Notifications.ClearAllNotifications() | Pushizo.Notifications.ClearAll() |
LegacySDK.InAppMessages.AddTrigger / AddTriggers / RemoveTrigger / RemoveTriggers / ClearTriggers / Paused + Clicked / WillDisplay / DidDisplay / WillDismiss / DidDismiss | same names + GetTriggers(), SetScreen(name) |
LegacySDK.Session.AddOutcome / AddUniqueOutcome / AddOutcomeWithValue | Pushizo.Session.SendEvent(name, properties, value) |
LegacySDK.ConsentRequired = true + LegacySDK.ConsentGiven = true | new PushizoOptions { RequiresPrivacyConsent = true } + Pushizo.SetConsentGiven(true) |
LegacySDK.Debug.LogLevel = … | Pushizo.Debug.SetLogLevel(LogLevel.Debug) |
| — | Pushizo.Inbox.*Async, Pushizo.User.GetPreferencesAsync / SetPreferencesAsync |
Android dependencies are resolved with EDM4U, and Assets/google-services.json is processed at build time (no Firebase Unity SDK required); on iOS, the Push capability, the NSE target and the Podfile are added by a post-build step. Details: Unity SDK.
5.11 Notification inbox and preferences (not available in the legacy provider)
- Notification inbox: messages sent with
add_to_inbox: trueare listed in a per-user inbox (Inbox.list,markRead,markAllRead,archive,unreadCount); since the legacy provider has no equivalent, there is no data to migrate. - Category preferences: instead of the legacy provider's "push categories" slidedown, you define Categories in the dashboard; the SDKs write user × channel opt-ins with
User.getPreferences()/setPreferences([...]). Preferences you managed with tags in the legacy provider (tags.promo_optin = "0") can be converted into real preferences after the migration with a one-timePUT /v1/apps/{app_id}/users/by/external_id/{id}/preferencescall.
6. Cutover plan (dual-write period)
- Week 0 — preparation: channels are validated, the player migration is complete, and the server integration also writes to Pushizo (dual-write: every notification/event goes to both the legacy provider and Pushizo; in Pushizo, send only to test devices with
test_devices_only: true, or limit the target to a small segment). - Weeks 1–2 — client release: publish the mobile version that includes the Pushizo SDK, and take the SDK live on the web. Both SDKs can run in the same app; however, request push permission only from Pushizo (if both SDKs ask for permission, users get confused), and on Android allow only one of them to show foreground notifications (
addForegroundLifecycleListener+preventDefault()). - Weeks 2–3 — traffic shift: start sending transactional notifications (orders, OTP) from Pushizo and campaigns from the dashboard. Reduce sending from the legacy provider segment by segment; compare delivery/open rates on the Analytics → Delivery report and Provider health pages.
- Weeks 3–4 — cutover: stop sending from the legacy provider, run a final delta pull with
migrate:legacy(imports are idempotent; new players are added and existing ones updated), turn off the legacy provider's webhooks/Event Streams and revoke the REST API key. - Old app versions: old versions that include the legacy provider SDK still register tokens with the legacy provider; keep running a weekly delta pull for these users until that version's usage share drops below 1%.
- Rollback: do not delete the legacy provider configuration during the dual-write period; if a critical problem occurs, you can move sending back to the legacy provider. After the cutover, remove the
.p8/service account keys from the legacy provider.
7. Common differences
| Topic | Legacy provider | Pushizo |
|---|---|---|
| Identity | Legacy ID + external_id | hs_id + external_id + custom aliases (users/by/{label}/{value}) |
| Device merging | login links the device to the user | Same; the anonymous user is merged and a user.merged webhook is produced |
| Error format | { "errors": [...] } | { "error": { "code": "HS_…", … } }, x-request-id |
| Rate limit | fixed | Plan-based (api_rps), X-RateLimit-* headers, 429 HS_RATE_LIMITED + Retry-After |
| Quiet hours / frequency cap | dashboard | App settings; per message quiet_hours_exempt, frequency_cap_exempt |
| Template language | {{ tag }} simple variables | Liquid ({{ user.tags.name }}, filters, conditions) |
| Web push identity | Legacy provider VAPID | Your own VAPID pair (generated when the channel is registered); subscriptions are recreated |
| Data residency | Legacy provider cloud (primary data center in the EU) | Region selection (EU/TR cells, data residency) or your own infrastructure (self-host) |
Runbook: APNs and FCM test sends to a real device
Follow this runbook to verify that channel credentials work with the real providers. In Phase 3 the "validate" endpoint opens a test connection to the provider; sending to a real device is completed with Phase 4 (POST /v1/notifications) and Phase 5…
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…