Cordova SDK
cordova-plugin-pushizo — a plugin wrapping the native Android and iOS SDKs over the cordova.exec bridge; push, in-app, notification inbox, preferences.
cordova-plugin-pushizo wraps the native Pushizo Android (com.pushizo:pushizo-android) and iOS (Pushizo pod) SDKs over the cordova.exec bridge. The surface is the same as the legacy provider's v5 and the Capacitor plugin; the queue, sessions, delivery feedback, trigger evaluation and in-app rendering live on the native side. Example: examples/cordova.
- cordova ≥ 12, cordova-android ≥ 12 (minSdk 24), cordova-ios ≥ 7 (iOS 15+).
- The plugin JS is loaded as
window.Pushizoandwindow.plugins.Pushizo; TypeScript types ship with the package (types/index.d.ts). - All methods return a
Promise; everyadd…listener call returns a function that removes the subscription.
Installation
cordova plugin add cordova-plugin-pushizo
# from inside the monorepo:
cordova plugin add ../../sdk/cordovaAndroid (FCM)
- Add an Android app in the Firebase console; put the
google-services.jsonfile at the project root and add it toconfig.xml(GradlePluginKotlinEnabledis required because the bridge is written in Kotlin):
<platform name="android">
<preference name="GradlePluginKotlinEnabled" value="true" />
<preference name="GradlePluginGoogleServicesEnabled" value="true" />
<preference name="GradlePluginGoogleServicesVersion" value="4.4.2" />
<resource-file src="google-services.json" target="app/google-services.json" />
</platform>- Dashboard → Channels → Android Push → Firebase service account JSON (you can pick Cordova in the setup wizard).
- The plugin depends on the
com.pushizo:pushizo-androidartifact (Maven Central 0.1.0). To try it locally from inside the monorepo, runcd sdk/android && gradle :pushizo:publishToMavenLocal; the plugin adds themavenLocal()repository itself. - The FCM service, the
POST_NOTIFICATIONSpermission and the notification Activity are merged from the SDK manifest. Notification icon: thecom.pushizo.sdk.default_notification_iconmeta-data inAndroidManifest.xml.
The plugin stores the initialize settings (only the app ID and public settings); when the process restarts because of a notification tap or an FCM message, the SDK is initialized before the WebView loads (PushizoInitProvider).
iOS (APNs)
config.xml:
<platform name="ios">
<preference name="deployment-target" value="15.0" />
<preference name="SwiftVersion" value="5" />
</platform>- The plugin adds the Push Notifications entitlement (
aps-environment) and theremote-notificationbackground mode itself. Dashboard → Channels → iOS Push →.p8key or.p12certificate. - Until the
Pushizopod is published, addpod 'Pushizo', :path => '<repo>/sdk/ios'toplatforms/ios/Podfileand runpod install. - The APNs token callbacks are added to the AppDelegate at runtime when the plugin loads; if the AppDelegate already has these methods, the token is forwarded to the SDK first and then your code runs. No extra code is needed.
- The Pushizo SDK takes over the
UNUserNotificationCenterdelegate; don't use it together with another push plugin (e.g.cordova-plugin-firebasex). - For rich media, badges and the
receivedrecord while the app is closed, add a Notification Service Extension target in Xcode (platforms/ios/*.xcworkspace), writetarget 'PushizoNSE' do pod 'Pushizo/Extension' endin the Podfile and delegate theNotificationServiceclass to thePushizoNotificationServiceExtension(appId:apiUrl:appGroup:)helper; enable the same App Group in the app and the NSE and writePushizoAppGroupto Info.plist. Becausecordova platform rm/add iosregenerates the Xcode project, you must add the NSE target again afterwards. Details: iOS SDK.
Initialization
document.addEventListener('deviceready', async () => {
// Add the click listener early; if the app was opened from a notification, the tap is delivered to the first listener.
Pushizo.Notifications.addClickListener((event) => {
console.log(event.notification.title, event.result.actionId, event.result.url);
});
await Pushizo.initialize('app_…', {
apiUrl: 'https://api.pushizo.com',
requiresPrivacyConsent: false,
logLevel: 'warn', // none | error | warn | info | debug
});
await Pushizo.setConsentGiven(true); // if requiresPrivacyConsent: true; no network calls are made until then
});initialize also accepts a single object: Pushizo.initialize({ appId: 'app_…', apiUrl }).
Permission
const granted = await Pushizo.Notifications.requestPermission(); // Android 13+ POST_NOTIFICATIONS, iOS UNAuthorization
const current = await Pushizo.Notifications.getPermission();
const stop = Pushizo.Notifications.addPermissionObserver(({ permission }) => {}); // removePermissionObserver(cb)Permission events come from the native Android/iOS SDK's permission observer (the result of a permission request, and changes made in settings when the app returns to the foreground; only on an actual change).
User, subscription, tags and aliases
await Pushizo.login('user_42', identityHash); // the hash is required if identity verification is on
await Pushizo.logout();
await Pushizo.User.addTag('plan', 'pro'); await Pushizo.User.addTags({ plan: 'pro', level: 3 }); // numbers/booleans are converted to strings
await Pushizo.User.removeTag('plan'); await Pushizo.User.removeTags(['plan', 'level']);
const tags = await Pushizo.User.getTags(); await Pushizo.User.setLanguage('tr');
await Pushizo.User.addAlias('crm_id', '1001'); // addAliases({ … }), removeAlias('crm_id')
const externalId = await Pushizo.User.getExternalId();
const hsId = await Pushizo.User.getId();
const emails = await Pushizo.User.getEmails(); // those registered with addEmail on this device; getSmsNumbers() works the same way
const state = await Pushizo.User.pushSubscription.getState(); // { id, token, optedIn, permission }
await Pushizo.User.pushSubscription.getId(); // getToken(), getOptedIn()
await Pushizo.User.pushSubscription.optIn(); await Pushizo.User.pushSubscription.optOut();
const unsubscribe = Pushizo.User.pushSubscription.addObserver((s) => {}); // removeObserver(cb)Email and SMS
await Pushizo.User.addEmail('ali@pushizo.com'); // INVALID_ARGUMENT if invalid
await Pushizo.User.removeEmail('ali@pushizo.com');
await Pushizo.User.addSms('+905551112233');
await Pushizo.User.removeSms('+905551112233');User preferences
const { preferences, categories } = await Pushizo.User.getPreferences();
const updated = await Pushizo.User.setPreferences([ // 1-100 records; returns the updated list
{ category: 'promo', optedIn: false }, // no channel/null = all channels
{ category: 'news', channel: 'email', optedIn: true }, // ios_push | android_push | web_push | email | sms
]);Without a subscription you get NOT_READY; proof of ownership is added by the native SDK. An undefined category gives HS_NOT_FOUND, and a channel the category doesn't cover gives HS_VALIDATION_ERROR. Category object: key, name/description (language code → text), channels, defaultOptedIn. Category model: Preferences.
Notification events
Pushizo.Notifications.addForegroundLifecycleListener((event) => {
event.preventDefault(); // don't show in the foreground; to show it later: await event.display()
});
Pushizo.Notifications.removeClickListener(cb); // removeForegroundLifecycleListener(cb)Events arrive from the native side over a single keepCallback channel; events that occur before the channel opens (e.g. a cold-start tap) are buffered natively. While a foreground listener exists, display is held until JS decides; on iOS, a blocked notification can be shown with display() within at most 25 s. Notification object: title, body, url, imageUrl, deliveryId, messageId, data, androidNotificationId (Android only).
In-app messages
await Pushizo.InAppMessages.addTrigger('level', 5); // addTriggers, removeTrigger(s), clearTriggers, getTriggers
await Pushizo.InAppMessages.setScreen('checkout'); // setScreen(null) when leaving the screen
await Pushizo.InAppMessages.setPaused(false); // await getPaused()
Pushizo.InAppMessages.addClickListener((e) => {}); // { message: { id }, result: { actionId, url } }
Pushizo.InAppMessages.addLifecycleListener({ willDisplay(e) {}, didDisplay(e) {}, willDismiss(e) {}, didDismiss(e) {} });Messages are rendered with the native SDK's view (Android Dialog, iOS UIWindow).
Notification inbox
const page = await Pushizo.Inbox.list({ limit: 20 }); // { items, unreadCount, nextCursor, hasMore }
await Pushizo.Inbox.markRead(page.items[0].id);
const unread = await Pushizo.Inbox.markAllRead();
await Pushizo.Inbox.archive(page.items[0].id);
const count = await Pushizo.Inbox.unreadCount();A registered subscription and user are required (otherwise NOT_READY). limit is 1-200 (default 50). Times are epoch milliseconds.
Content cards
const feed = await Pushizo.ContentCards.list(20); // { cards, unviewedCount }
await Pushizo.ContentCards.logImpression(feed.cards[0].id);
await Pushizo.ContentCards.logClick(id); // click (also counts as an impression)
await Pushizo.ContentCards.dismiss(id); // removes it from the feedCards do not appear in the notification inbox; the feed is ordered pinned → priority → newest. limit is 1-100 (default 50). A registered subscription and user are required (otherwise NOT_READY). Log an impression when a card is shown and a click when it is tapped; the stats appear on the campaign detail page.
Android delivery hardening
On vendors such as Xiaomi, Huawei, Oppo, Vivo and Samsung, the battery and auto-start manager stops apps in the background, so notifications arrive late or not at all. Pushizo.Delivery reads the restrictions on the device and takes the user to the relevant settings screen. Details: Android delivery hardening.
const status = await Pushizo.Delivery.status(); // { supported, vendor, rom, risk, restricted, recommendedSettings, … }
if (await Pushizo.Delivery.shouldShowGuidance()) { // at risk and the dialog was not shown in the last 14 days
const opened = await Pushizo.Delivery.showGuidance(); // ready-made dialog (22 languages); opens the settings screen if accepted
}
await Pushizo.Delivery.openSettings('auto_start'); // from your own UIrisk: none, elevated, high. Screens: auto, notifications, auto_start, battery_optimization, app_details (TypeError for an invalid value). shouldShowGuidance(30) changes the interval and showGuidance({ setting, message }) the screen and the text; the SDK never shows the dialog on its own. Android only: on iOS status() returns supported: false and risk: 'none', and openSettings and showGuidance return false without doing anything.
Profile, consent, advertising ID and badge
await Pushizo.login('user_42', { jwt, profile: { email: 'ali@ornek.com', sms: '+905551112233', tags: { plan: 'pro' }, aliases: { crm: 'c-1' } } });
await Pushizo.User.setAdsPersonalizationConsent(true); // ads personalization consent; returns the current preferences
const consents = await Pushizo.User.getConsents(); // [{ purpose, granted, source, updatedAt }]
await Pushizo.Ads.setAdvertisingId(gaidOrIdfa); // null deletes the record
const shown = await Pushizo.Notifications.setBadgeCount(3); // true when this device can show the badge
await Pushizo.Notifications.clearBadge();
if (await Pushizo.Location.permissionGranted() && !(await Pushizo.Location.backgroundPermissionGranted())) {
await Pushizo.Location.requestBackgroundPermission('To let you know when you are near a store'); // same as requestAlwaysPermission on iOS
}
const listening = await Pushizo.Chat.isListening();
const ready = await Pushizo.isInitialized();The login profile writes the email, SMS number, tags and aliases in the same call as the login; an invalid email, phone number or alias is rejected with INVALID_ARGUMENT before the login (validation lives in the native SDKs: Android login(id, HsUserProfile), iOS login(_:profile:)). Ads.setAdvertisingId takes the ID from your app (the SDK ships no ad library and no ATT prompt); the ID reaches an audience only for users with the ads_personalization consent, and only as a SHA-256 hash. setBadgeCount and clearBadge return true when this device can show the badge: on iOS they set the app badge and the counter shared with the notification extension (always true); Android has no "set the count" API for the launcher badge, so the native SDK stores the count and writes it to the following notifications (false before Android 8, or when notifications or the channel badge are turned off). Notifications.getBadgeCount() returns the current count. Location.permissionGranted() and backgroundPermissionGranted() are read from the native SDK and never prompt. requestBackgroundPermission(rationale?) and requestAlwaysPermission() request the same permission (Android ACCESS_BACKGROUND_LOCATION, iOS "Always"); they return false when the permission is not declared in the app's manifest or Info.plist. User.registerAdm(token) writes the Fire OS ADM registration ID (Android only; does nothing on iOS).
User properties, observers, event ID and the built-in chat screen
await Pushizo.User.setProperty('plan', 'pro'); // string, number, boolean
await Pushizo.User.setProperty('address', { city: 'İzmir', tags: ['vip'] }); // array / plain object
await Pushizo.User.setProperty('plan', null); // null deletes the property
const removeFlags = Pushizo.FeatureFlags.addObserver(async () => {
applyTheme(await Pushizo.FeatureFlags.getValue('theme', 'light'));
});
const removeInbox = Pushizo.Inbox.addObserver(({ type, itemId, unreadCount }) => setBadge(unreadCount));
// When the same ID is given to the ad pixel, the server deduplicates the event.
await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9, { eventId: 'order_42:purchase' });
await Pushizo.Chat.show(); // built-in chat screen
if (await Pushizo.Chat.isPresented()) await Pushizo.Chat.hide();User.setProperty(key, value) writes a user property and null deletes it; key is 1-64 characters and value is a string, a finite number, a boolean, or an array/plain object of those (a nested null, a Date or a function throws TypeError). FeatureFlags.addObserver(cb) is called every time the flag values are refreshed from the server (at session start and on refresh()). Inbox.addObserver(cb) delivers the inbox change event (type: listed, read, read_all, archived, count; itemId only on single-item events; unreadCount is the current unread count): read / read_all / archived are reported on every operation, listed / count only when the unread count changes. Both addObserver calls return a function that removes the subscription; removeObserver(cb) does the same. The eventId in the fourth argument of sendEvent is the deduplication ID (8-64 characters; letters, digits and . _ : -); when the format is invalid the native SDK generates its own ID. Chat.show() opens the built-in chat screen (Android HsChatActivity, iOS modal HSChatViewController), Chat.hide() closes it and Chat.isPresented() tells whether it is open; before initialize, show() is rejected with NOT_READY. The native Android SDK doesn't expose the presentation state, so the bridge tracks the HsChatActivity lifecycle. Native views (HsChatView, HsContentCardsView) and InAppMessages.setRenderer can't be bridged.
Events (outcomes) and the notification tray
await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9); // the name also fires in-app event triggers
await Pushizo.Notifications.clearAll();
await Pushizo.Notifications.removeGroupedNotifications('orders'); // Android android_group / iOS thread-id
await Pushizo.Notifications.removeNotification(id); // Android: notification.androidNotificationId (integer)
await Pushizo.Notifications.removeNotification('request-id'); // iOS: UNNotificationRequest.identifier
await Pushizo.Debug.setLogLevel('debug');Error codes
Errors are PushizoError instances and carry a code field:
| Code | Meaning |
|---|---|
INVALID_ARGUMENT | Invalid email/phone or a missing field. |
NOT_READY | initialize wasn't called, or the subscription/user isn't registered yet. |
NOT_FOUND | The deferred foreground notification wasn't found or was already shown (event.display()). |
NOT_IMPLEMENTED | Method not defined on the native side (the plugin JS and native code versions don't match). |
HS_… | Server error code; catalog: Errors. |
Empty/invalid arguments throw TypeError / RangeError before reaching the bridge.
Testing
cd sdk/cordova && npm install && npm run typecheck && npm test && npm run buildnpm run build compiles src/*.ts into www/*.js (published with the plugin and kept in the repository).
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| Android build stops with a Kotlin error | GradlePluginKotlinEnabled isn't enabled in config.xml. |
Android: pushizo-android can't be resolved | publishToMavenLocal wasn't run. |
| Click/foreground events don't arrive on iOS | Another push plugin is taking over the UNUserNotificationCenter delegate; remove it. |
| The NSE target disappeared | After cordova platform rm/add ios, add the target and the Podfile entry again. |
requestPermission always false | Permission denied on Android 13+; Push capability missing on iOS. Other symptoms: Android, iOS. |
Capacitor (Ionic) SDK
@pushizo/capacitor — a Capacitor 6/7 plugin wrapping the native Android and iOS SDKs; delegates to @pushizo/web on the web. Push, in-app, notification inbox, preferences.
.NET MAUI SDK
Pushizo.Maui — a .NET MAUI package (net8.0/net9.0) wrapping the native Android and iOS SDKs over a JSON bridge; push, in-app, notification inbox, preferences.