PushizoDocs
SDK guides

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.Pushizo and window.plugins.Pushizo; TypeScript types ship with the package (types/index.d.ts).
  • All methods return a Promise; every add… listener call returns a function that removes the subscription.

Installation

cordova plugin add cordova-plugin-pushizo
# from inside the monorepo:
cordova plugin add ../../sdk/cordova

Android (FCM)

  1. Add an Android app in the Firebase console; put the google-services.json file at the project root and add it to config.xml (GradlePluginKotlinEnabled is 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>
  1. Dashboard → Channels → Android Push → Firebase service account JSON (you can pick Cordova in the setup wizard).
  2. The plugin depends on the com.pushizo:pushizo-android artifact (Maven Central 0.1.0). To try it locally from inside the monorepo, run cd sdk/android && gradle :pushizo:publishToMavenLocal; the plugin adds the mavenLocal() repository itself.
  3. The FCM service, the POST_NOTIFICATIONS permission and the notification Activity are merged from the SDK manifest. Notification icon: the com.pushizo.sdk.default_notification_icon meta-data in AndroidManifest.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)

  1. config.xml:
<platform name="ios">
    <preference name="deployment-target" value="15.0" />
    <preference name="SwiftVersion" value="5" />
</platform>
  1. The plugin adds the Push Notifications entitlement (aps-environment) and the remote-notification background mode itself. Dashboard → Channels → iOS Push → .p8 key or .p12 certificate.
  2. Until the Pushizo pod is published, add pod 'Pushizo', :path => '<repo>/sdk/ios' to platforms/ios/Podfile and run pod install.
  3. 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.
  4. The Pushizo SDK takes over the UNUserNotificationCenter delegate; don't use it together with another push plugin (e.g. cordova-plugin-firebasex).
  5. For rich media, badges and the received record while the app is closed, add a Notification Service Extension target in Xcode (platforms/ios/*.xcworkspace), write target 'PushizoNSE' do pod 'Pushizo/Extension' end in the Podfile and delegate the NotificationService class to the PushizoNotificationServiceExtension(appId:apiUrl:appGroup:) helper; enable the same App Group in the app and the NSE and write PushizoAppGroup to Info.plist. Because cordova platform rm/add ios regenerates 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 feed

Cards 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 UI

risk: 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:

CodeMeaning
INVALID_ARGUMENTInvalid email/phone or a missing field.
NOT_READYinitialize wasn't called, or the subscription/user isn't registered yet.
NOT_FOUNDThe deferred foreground notification wasn't found or was already shown (event.display()).
NOT_IMPLEMENTEDMethod 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 build

npm run build compiles src/*.ts into www/*.js (published with the plugin and kept in the repository).

Troubleshooting

SymptomCause / fix
Android build stops with a Kotlin errorGradlePluginKotlinEnabled isn't enabled in config.xml.
Android: pushizo-android can't be resolvedpublishToMavenLocal wasn't run.
Click/foreground events don't arrive on iOSAnother push plugin is taking over the UNUserNotificationCenter delegate; remove it.
The NSE target disappearedAfter cordova platform rm/add ios, add the target and the Podfile entry again.
requestPermission always falsePermission denied on Android 13+; Push capability missing on iOS. Other symptoms: Android, iOS.

On this page