PushizoDocs
Migration

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

StepDurationOutput
1. Create the account, organization and app10 minapp_… ID
2. Channel credentials (APNs .p8, FCM service account, VAPID, email/SMS)30 minChannels active
3. Player/subscription migration (migrate:legacy → CSV → import)depends on file sizeUsers, tags, iOS/Android/email/SMS subscriptions
4. Server integration (REST → Pushizo public API / server SDKs)1–3 daysNotification, user and event calls
5. Client SDK replacement (Web/iOS/Android/Flutter, React Native/Capacitor/Cordova/.NET MAUI/Unity)1–2 daysNew version release
6. Dual-write period and cutover2–4 weeksThe legacy provider is shut down

2. Creating an account and app

  1. 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.
  2. Create the app with the Getting started wizard (/<org>/getting-started) or through the public API: POST /v1/apps (requires an org-wide admin key).
  3. 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, an admin-scoped key with an IP allowlist and an expiry date is recommended.
  4. On the Channels page, enter the same credentials you used with the legacy provider:
Legacy provider settingPushizo channelNotes
Apple → .p8 key, Key ID, Team ID, Bundle IDiOS Push (ios_push)Environment sandbox / production; the same .p8 works on both sides.
Google → Firebase service account JSONAndroid Push (android_push)The same Firebase project is used; device tokens remain valid.
Web → Safari/Chrome settingsWeb 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 columnPushizo fieldRule
external_user_idexternal_idIf empty and identifier is present, an anonymous user is created; if both are empty, the row goes to the error report.
identifiersubscription tokenPush token / email / phone. Emails are lowercased and phone numbers normalized to E.164; invalid values cause the row to be skipped.
device_typesubscription channel0 → 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 = tsubscription status: invalid
notification_types < 0subscription status: unsubscribedOtherwise subscribed.
tags (JSON)user tagsValues are converted to strings (objects/arrays become JSON text, null is skipped). Invalid JSON → row error.
languageproperties.language, device.locale
timezone (seconds from UTC)device.timezoneEtc/GMT∓h if it is a whole hour (UTC+3 → Etc/GMT-3), otherwise empty.
device_model, device_os, game_versiondevice.model, device.os_version, device.app_version
session_count, created_at, last_activesession_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_url file (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 RESTPushizo public APIDifference
POST /notificationsPOST /v1/notificationsapp_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}/historyGET /v1/notifications/{message_id}/historyCSV job; download_url when complete.
POST /notifications/{id}/export_eventsPOST /v1/notifications/{message_id}/export_eventsCSV 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_exportPOST /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 /usersPOST /v1/apps/{app_id}/usersexternal_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}/identityGET/PATCH /v1/apps/{app_id}/users/by/{label}/{value}/identityAdds aliases; DELETE …/identity/{alias_label} removes one.
POST /users/by/{label}/{value}/subscriptionsPOST /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}/ownerPOST /v1/apps/{app_id}/subscriptions/{subscription_id}/owner{ external_id }.
GET /subscriptions/{id}/user/identityGET /v1/apps/{app_id}/subscriptions/{subscription_id}/user/identity
POST /apps/{app_id}/custom_eventsPOST /v1/apps/{app_id}/events[{ external_id | subscription_id, name, properties, value, occurred_at }], up to 500.
GET /apps/{app_id}/outcomesGET /v1/apps/{app_id}/analytics/conversionsA 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 /templatesGET/POST /v1/apps/{app_id}/templates, PATCH/DELETE …/{id}, POST …/{id}/renderLiquid; 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 /appsPOST /v1/appsOrg-wide admin key.
Automations (dashboard only)GET/POST /v1/apps/{app_id}/journeys, …/draft, …/publish, …/runsCan be designed and triggered through the API (journeys).
In-App Messages (dashboard only)GET/POST /v1/apps/{app_id}/in-app-messagesBlock-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/typesThere 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 providerPushizoNote
included_segments / excluded_segmentstarget.included_segments / target.excluded_segmentsSegment IDs (seg_…) or names.
include_aliases: { external_id: [] }target.include_aliases or target.include_external_idsUp to 2000.
include_subscription_ids (formerly include_player_ids)target.include_subscription_ids
include_email_tokenstarget.email_toFor an address without a subscription, an anonymous user + subscription is created.
include_phone_numberstarget.include_phone_numbersE.164.
filterstarget.filtersSegment 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, isAnyWebtarget.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, namesame namepriority is 5 (normal) or 10 (high), as with the legacy provider; ttl is in seconds.
ios_badgeType, ios_badgeCountios_badge_type, ios_badge_countsnake_case.
ios_interruption_levelios_interruption_levelpassive, active, time-sensitive, critical (critical alert guide).
external_id (idempotency)idempotency_key or the Idempotency-Key headerThe same key + the same body returns the same response; a different body returns 409 HS_IDEMPOTENCY_CONFLICT.
send_after + delayed_option: "timezone"samedelivery_time_of_day: "09:00".
throttle_rate_per_minutethrottle_rate_per_minute
email_mjmlemail_mjmlNot 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_interactionAdditional 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 rootPushizoSDKWorker.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 / getTagssame names: Pushizo.User.addTag / addTags / removeTag / removeTags / getTags
LegacySDK.User.addAlias / addAliases / removeAliassame names
LegacySDK.User.addEmail / removeEmail / addSms / removeSmssame names (addresses are normalized on the client)
LegacySDK.User.setLanguagePushizo.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() / permissionPushizo.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 / promptPushCategoriesPushizo.Slidedown.promptPush / promptEmail / promptSms / promptEmailAndSms (User.setPreferences for category preferences)
promptOptions.slidedown, welcomeNotification, notificationClickHandlerMatch/Action, notifyButtonslidedown, welcomeNotification, notificationClickHandlerMatch / notificationClickHandlerAction, bell (init options)
LegacySDK.Session.sendOutcome / sendUniqueOutcome / sendOutcomeWithValuePushizo.Session.sendEvent(name, properties?, value?)
LegacySDK.User.PushSubscription no notification inboxPushizo.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.setLogLevelPushizo.Debug.setLogLevel('debug')

Details: Web SDK; framework integrations: React, Vue, Angular; iOS Safari PWA: iOS web push.

5.2 iOS

Legacy provider iOS SDK 5Pushizo iOS SDK (Pushizo, PushizoExtension)
LegacySDK.initialize("APP_ID", withLaunchOptions:)Pushizo.initialize("app_…", launchOptions:) { options in options.apiUrl = "https://api.pushizo.com" }
Token via swizzlingNo 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/setLanguagesame names
LegacySDK.User.addEmail/addSms/removeEmail/removeSmssame names
LegacySDK.User.pushSubscription.optIn()/optOut()/id/token/optedIn + addObserverPushizo.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.addPermissionObserveraddPermissionObserver { granted in } → HSListenerToken; removePermissionObserver(token)
addClickListener / addForegroundLifecycleListenersame names; they return a token (removeClickListener(token))
LegacyNotificationServiceExtensionPushizoNotificationServiceExtension(appId:apiUrl:appGroup:) → didReceive, serviceExtensionTimeWillExpire
LegacySDK.InAppMessages.addTrigger/removeTrigger/clearTriggers/pausedsame names + setScreen, addClickListener, addLifecycleListener
LegacySDK.Session.sendOutcome(_:)Pushizo.Session.sendEvent("name", properties:, value:)
LegacySDK.setConsentRequired/setConsentGivenoptions.requiresPrivacyConsent = true + Pushizo.setConsentGiven(true)
LegacySDK.Notifications.clearAll()Pushizo.Notifications.clearAll(), removeGroupedNotifications, removeNotification(identifier:)
Live ActivitiesPushizo.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 5Pushizo 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/setLanguagesame names
LegacySDK.User.addEmail/addSms/removeEmail/removeSmssame names (emails, smsNumbers lists)
LegacySDK.User.pushSubscription.optIn()/optOut()/id/token/optedIn + addObserversame names (plus state)
LegacySDK.Notifications.requestPermission(fallbackToSettings) (coroutine)Pushizo.Notifications.requestPermission(activity) + Pushizo.Notifications.onPermissionResult() in onRequestPermissionsResult (PERMISSION_REQUEST_CODE)
addPermissionObserveraddPermissionObserver(observer) / removePermissionObserver(observer)
addClickListener / addForegroundLifecycleListenersame names
LegacySDK.InAppMessages.addTrigger/…/pausedsame names + setScreen, addClickListener, addLifecycleListener
LegacySDK.Session.sendOutcomePushizo.Session.sendEvent("name", mapOf(...), value)
LegacySDK.consentRequired = true / consentGiven = trueOptions(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 packagepushizo_flutter
LegacySDK.initialize("APP_ID")await Pushizo.initialize('app_…', apiUrl: 'https://api.pushizo.com')
LegacySDK.login/logoutPushizo.login(externalId, identityHash: null) / Pushizo.logout()
LegacySDK.User.addTags/removeTag/getTags/setLanguagesame names (all return a Future)
LegacySDK.User.addEmail/addSms/removeEmail/removeSmssame names
LegacySDK.User.pushSubscription.optIn/optOut/id/token/optedIn + addObserverPushizo.User.pushSubscription.optIn()/optOut(), await state, changes.listen(...)
LegacySDK.Notifications.requestPermission(true)await Pushizo.Notifications.requestPermission()
LegacySDK.Notifications.addPermissionObserverPushizo.Notifications.addPermissionObserver(fn) or permissionStream.listen(...)
addClickListener / addForegroundWillDisplayListenerPushizo.Notifications.clickStream.listen(...) / foregroundStream.listen(...)
LegacySDK.InAppMessages.addTrigger/…/paused(bool)same names + setScreen, setPaused(bool), clickStream, lifecycleStream, setNavigatorKey
LegacySDK.Session.sendOutcomePushizo.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 the UNUserNotificationCenter delegate on iOS, two push SDKs must not coexist in the same release.
  • initialize takes 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, addOutcomeWithValue and their C# equivalents) become a single Session.sendEvent(name, properties?, value?) call; the same name also fires in-app event triggers. 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 swizzlingNo 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 / getTagssame names
LegacySDK.User.addAlias / addAliases / removeAliassame names
LegacySDK.User.addEmail / removeEmail / addSms / removeSms, setLanguagesame 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 / getPausedsame names + getTriggers, setScreen
LegacySDK.InAppMessages.addEventListener('click' | 'willDisplay' | 'didDisplay' | 'willDismiss' | 'didDismiss', …)same event names; event payload { messageId, actionId, url } / { messageId }
LegacySDK.Session.addOutcome / addUniqueOutcome / addOutcomeWithValuePushizo.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 pluginnpm install @pushizo/capacitor (+ @pushizo/web for web), npx cap sync
iOS token obtained via swizzlingPost the capacitorDidRegisterForRemoteNotifications / capacitorDidFailToRegisterForRemoteNotifications notifications in AppDelegate.swift
LegacySDK.initialize('APP_ID')await Pushizo.initialize('app_…', { apiUrl: 'https://api.pushizo.com' })
LegacySDK.login / logoutPushizo.login(externalId, identityHash?) / Pushizo.logout() (Promise)
LegacySDK.User.addTag / addTags / removeTag / removeTags / getTags, addAlias / addAliases / removeAlias, addEmail / removeEmail / addSms / removeSms, setLanguagesame names (all return a Promise)
LegacySDK.User.pushSubscription.getIdAsync / getTokenAsync / getOptedInAsync / optIn / optOutPushizo.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 / getPausedsame names + getTriggers, setScreen
LegacySDK.InAppMessages.addEventListener('click' | 'willDisplay' | …, cb)Pushizo.InAppMessages.addClickListener(cb) / addLifecycleListener({ willDisplay, didDisplay, willDismiss, didDismiss })
LegacySDK.Session.addOutcome / addUniqueOutcome / addOutcomeWithValuePushizo.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 5cordova-plugin-pushizo
cordova plugin add legacy Cordova plugin, window.plugins.LegacySDKcordova plugin add cordova-plugin-pushizo, window.Pushizo (and window.plugins.Pushizo)
No Android Gradle setting requiredconfig.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 callsIdentical 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 5Pushizo.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 swizzlingPushizoIos.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 / RemoveSmssame names + GetTags(), SetLanguage("tr")
LegacySDK.User.PushSubscription.OptIn() / OptOut() / Id / Token / OptedIn + Changedsame names (e.Previous, e.Current)
await LegacySDK.Notifications.RequestPermissionAsync(true)await Pushizo.Notifications.RequestPermissionAsync(fallbackToSettings: true)
LegacySDK.Notifications.Clicked / ForegroundWillDisplay / PermissionChangedsame 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 / DidDismisssame names + GetTriggers(), SetScreen(name)
LegacySDK.Session.AddOutcome / AddUniqueOutcome / AddOutcomeWithValuePushizo.Session.SendEvent(name, properties, value)
LegacySDK.ConsentRequired = true + LegacySDK.ConsentGiven = trueo.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 5com.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 / RemoveSmssame names + GetTags(), SetLanguage("tr")
LegacySDK.User.PushSubscription.OptIn() / OptOut() / Id / Token / OptedIn + Changedsame 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 / DidDismisssame names + GetTriggers(), SetScreen(name)
LegacySDK.Session.AddOutcome / AddUniqueOutcome / AddOutcomeWithValuePushizo.Session.SendEvent(name, properties, value)
LegacySDK.ConsentRequired = true + LegacySDK.ConsentGiven = truenew 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: true are 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-time PUT /v1/apps/{app_id}/users/by/external_id/{id}/preferences call.

6. Cutover plan (dual-write period)

  1. 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).
  2. 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()).
  3. 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.
  4. 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.
  5. 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%.
  6. 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

TopicLegacy providerPushizo
IdentityLegacy ID + external_idhs_id + external_id + custom aliases (users/by/{label}/{value})
Device merginglogin links the device to the userSame; the anonymous user is merged and a user.merged webhook is produced
Error format{ "errors": [...] }{ "error": { "code": "HS_…", … } }, x-request-id
Rate limitfixedPlan-based (api_rps), X-RateLimit-* headers, 429 HS_RATE_LIMITED + Retry-After
Quiet hours / frequency capdashboardApp settings; per message quiet_hours_exempt, frequency_cap_exempt
Template language{{ tag }} simple variablesLiquid ({{ user.tags.name }}, filters, conditions)
Web push identityLegacy provider VAPIDYour own VAPID pair (generated when the channel is registered); subscriptions are recreated
Data residencyLegacy provider cloud (primary data center in the EU)Region selection (EU/TR cells, data residency) or your own infrastructure (self-host)

On this page