PushizoDocs
SDK guides

React Native SDK

@pushizo/react-native — a TurboModule bridge wrapping the native Android and iOS SDKs, plus an Expo config plugin; push, in-app, notification inbox, preferences.

@pushizo/react-native wraps the native Android (com.pushizo:pushizo-android) and iOS (Pushizo) SDKs: the queue, sessions, delivery feedback (received/opened), trigger evaluation and in-app rendering run on the native side. The surface is compatible with the legacy provider's v5 React Native API. Example: examples/react-native (bare RN 0.87, New Architecture).

  • React Native ≥ 0.74; both the New Architecture (TurboModule, codegen RNPushizoSpec) and the old architecture are supported.
  • Android minSdk 24, iOS 15.0+.
  • Expo: development builds only (expo prebuild / EAS Build); Expo Go is not supported because it doesn't include native modules.

Installation

npm install @pushizo/react-native

Android

  1. Add an Android app in the Firebase console and put the google-services.json file under android/app/. Add classpath("com.google.gms:google-services:4.4.2") to android/build.gradle → buildscript.dependencies, and apply plugin: "com.google.gms.google-services" to android/app/build.gradle.
  2. Dashboard → Channels → Android Push → Firebase service account JSON.
  3. INTERNET, POST_NOTIFICATIONS and the FCM service are merged automatically from the native SDK manifest. For the default notification icon, add inside <application>:
<meta-data android:name="com.pushizo.sdk.default_notification_icon" android:resource="@drawable/ic_notification" />
  1. If you build from inside the monorepo, android/settings.gradle:
include ':pushizo'
project(':pushizo').projectDir = new File(rootProject.projectDir, '../../../sdk/android/pushizo')

Without this module, the bridge uses the com.pushizo:pushizo-android artifact (Maven Central or publishToMavenLocal).

iOS

  1. cd ios && pod install. For local development: ios/Podfile → pod 'Pushizo', :path => '<repo>/sdk/ios'.
  2. Xcode → target → Signing & Capabilities: Push Notifications, Background Modes → Remote notifications and (for badge/NSE sharing) App Groups (group.<bundle id>.pushizo).
  3. The SDK doesn't use swizzling; forward the APNs token from AppDelegate:
import Pushizo

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  Pushizo.setDeviceToken(deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  Pushizo.setDeviceTokenError(error)
}

Objective-C AppDelegate.mm: #import <PushizoReactNative/PushizoRNPush.h> and, in the same methods, [PushizoRNPush didRegisterForRemoteNotificationsWithDeviceToken:deviceToken] / [PushizoRNPush didFailToRegisterForRemoteNotificationsWithError:error].

  1. Dashboard → Channels → iOS Push → .p8 key (Key ID, Team ID).
  2. For rich media, action buttons, badge increments and the received record, add a Notification Service Extension: add the target and copy sdk/react-native/plugin/templates/PushizoNotificationServiceExtension/NotificationService.swift, add PushizoAppId (optionally PushizoApiUrl, PushizoAppGroup) to the target's Info.plist and write target 'PushizoNotificationServiceExtension' do pod 'Pushizo/Extension' end in the Podfile. Details: iOS SDK.

Expo

{
  "expo": {
    "ios": { "bundleIdentifier": "com.pushizo.app" },
    "android": { "package": "com.pushizo.app", "googleServicesFile": "./google-services.json" },
    "plugins": [
      ["@pushizo/react-native", { "mode": "development", "appId": "app_…", "androidSmallIcon": "./assets/notification-icon.png", "androidAccentColor": "#FF5A1F" }]
    ]
  }
}

Then run npx expo prebuild (or EAS Build). On iOS the plugin adds aps-environment, Background Modes, the App Group, AppDelegate token forwarding, Info.plist keys and the PushizoNotificationServiceExtension target; on Android it adds POST_NOTIFICATIONS, the small icon, the accent color and early-initialization meta-data; if android.googleServicesFile is set, it copies the file to android/app/google-services.json and applies the com.google.gms.google-services Gradle plugin (idempotent). Early initialization reads requiresPrivacyConsent and logLevel from Info.plist on iOS (PushizoRequiresPrivacyConsent, PushizoLogLevel) and from manifest meta-data on Android; if consent is required, the SDK makes no network calls even before the JS loads.

OptionDescription
modeRequired. development | production (APNs environment; production for TestFlight/App Store).
appIdFor early initialization and the NSE; required when the NSE is enabled.
apiUrl, requiresPrivacyConsent, logLevelEarly initialization settings (must match the JS initialize).
iosAppGroupApp Group starting with group. (default group.<bundle id>.pushizo).
iosNotificationServiceExtensionNSE target (default true).
iosDeploymentTarget, devTeamNSE deployment target (default 15.0) and signing team.
iosSdkPath, androidSdkPathMonorepo: links the native SDKs from source.
androidSmallIcon, androidAccentColorPNG icon (white shape, transparent background) and #RRGGBB accent color.
androidDefaultChannelId, androidDefaultChannelNameDefault notification channel for early initialization (must match JS defaultChannelId / defaultChannelName).

Invalid options stop prebuild with an error that tells you which field to fix and how.

Initialization

import { Pushizo, LogLevel } from '@pushizo/react-native';

await Pushizo.initialize('app_…', {
  apiUrl: 'https://api.pushizo.com',
  requiresPrivacyConsent: false,
  logLevel: LogLevel.Warn,
  // iOS: appGroup, apnsEnvironment, provisionalAuthorization · Android: defaultChannelId, defaultChannelName
});

Pushizo.setConsentGiven(true);   // if requiresPrivacyConsent: true; false clears the queue and the local identity

A second initialize with the same appId doesn't re-create the native SDK. To have the SDK start before the JS loads on a cold start (session start, iOS notification center delegate), add the com.pushizo.reactnative.app_id meta-data (optionally …api_url, …requires_privacy_consent, …log_level) inside <application> on Android, and Info.plist PushizoAppId (optionally PushizoApiUrl) on iOS; the Expo plugin adds these when appId is set.

Permission

const granted = await Pushizo.Notifications.requestPermission();   // Android 13+ POST_NOTIFICATIONS, iOS UNAuthorization
const current = await Pushizo.Notifications.getPermissionAsync();  // queries the system
Pushizo.Notifications.permission;                                  // last known state (synchronous)
Pushizo.Notifications.addEventListener('permissionChange', ({ permission }) => {});

permissionChange comes from the native SDK's permission observer: it is sent only on an actual change, when a permission request completes and when the app returns to the foreground (if it was changed in settings). Without permission the subscription stays pending; it is registered automatically once permission is granted.

User, subscription, tags and aliases

await Pushizo.login('user_42', identityHashFromBackend);   // the hash is required if identity verification is on
Pushizo.logout();

await Pushizo.User.addTag('plan', 'pro');     await Pushizo.User.addTags({ plan: 'pro', city: 'istanbul' });
await Pushizo.User.removeTag('plan');         await Pushizo.User.removeTags(['plan', 'city']);
const tags = await Pushizo.User.getTags();    await Pushizo.User.setLanguage('tr');
await Pushizo.User.addAlias('crm_id', '1001'); // addAliases({ … }) (at most 20), removeAlias('crm_id')
const externalId = await Pushizo.User.getExternalId();
const hsId = await Pushizo.User.getPushizoId();
const emails = await Pushizo.User.getEmails();     // those registered with addEmail on this device; getSmsNumbers() works the same way

const subId = await Pushizo.User.pushSubscription.getIdAsync();
const token = await Pushizo.User.pushSubscription.getTokenAsync();
const optedIn = await Pushizo.User.pushSubscription.getOptedInAsync();
Pushizo.User.pushSubscription.optIn();        Pushizo.User.pushSubscription.optOut();
Pushizo.User.pushSubscription.addEventListener('change', ({ previous, current }) => {}); // id, token, optedIn, permission

Email and SMS

await Pushizo.User.addEmail('Ali@Pushizo.com');     // → ali@pushizo.com; INVALID_ARGUMENT if invalid
await Pushizo.User.removeEmail('ali@pushizo.com');
await Pushizo.User.addSms('+90 532 123 45 67');      // → +905321234567 (E.164)
await Pushizo.User.removeSms('+905321234567');

User preferences

const { preferences, categories } = await Pushizo.User.getPreferences();
for (const c of categories) console.log(c.key, c.name.tr ?? c.name.en, c.channels, c.defaultOptedIn);
const updated = await Pushizo.User.setPreferences([
  { category: 'promo', optedIn: false },                   // no channel/null = all channels
  { category: 'news', channel: 'email', optedIn: true },  // ios_push | android_push | web_push | email | sms
]);

If the subscription isn't registered yet you get NOT_READY. Input is validated before it crosses the bridge (1-100 records, category 1-64 characters, a known channel or null); invalid input throws TypeError. Proof of ownership is added by the native SDK. UserPreference: category, channel, optedIn, explicit, source, updatedAt (epoch ms). Category model: Preferences.

Notification events

Pushizo.Notifications.addEventListener('click', (e) => {
  console.log(e.notification.title, e.notification.data, e.result.actionId, e.result.url);
});
Pushizo.Notifications.addEventListener('foregroundWillDisplay', (e) => {
  if (e.getNotification().data.silent === '1') e.preventDefault();  // don't show in the foreground
  // async decision: e.preventDefault(); then (≤ 25 s) e.getNotification().display();
});
Pushizo.Notifications.removeEventListener('click', listener);

When the app is opened by tapping a notification, the tap is held natively until a click listener is added in JS. Without a foregroundWillDisplay listener, the native SDK displays the notification itself. Notification object: title, body, url, imageUrl, deliveryId, messageId, data.

In-app messages

await Pushizo.InAppMessages.addTrigger('level', 'gold');  // addTriggers({…}), removeTrigger(s), clearTriggers(), getTriggers()
Pushizo.InAppMessages.setScreen('cart');                   // setScreen(null) when leaving the screen
Pushizo.Session.sendEvent('cart_viewed');
Pushizo.InAppMessages.setPaused(true);                     // await Pushizo.InAppMessages.getPaused()
Pushizo.InAppMessages.addEventListener('click', ({ messageId, actionId, url }) => {});
Pushizo.InAppMessages.addEventListener('didDisplay', ({ messageId }) => {}); // willDisplay | didDisplay | willDismiss | didDismiss

Messages are displayed with the native SDK's default rendering (Android Dialog, iOS UIWindow). Trigger keys are 1-64 characters and values at most 200 characters; trigger rules, frequency and actions are identical across all SDKs.

Notification inbox

const page = await Pushizo.Inbox.list({ limit: 20, cursor: null }); // items, unreadCount, nextCursor, hasMore
const item = await Pushizo.Inbox.markRead(page.items[0].id);
const remaining = await Pushizo.Inbox.markAllRead();
await Pushizo.Inbox.archive(item.id);
const unread = await Pushizo.Inbox.unreadCount();
const stop = Pushizo.Inbox.addObserver(({ type, itemId, unreadCount }) => setBadge(unreadCount)); // stop() removes it

limit is 1-200 (default 50; RangeError if out of range). Times (readAt, archivedAt, expiresAt, createdAt) are epoch milliseconds. addObserver reports inbox changes: type is listed, read, read_all, archived or count; listed and count only fire when the unread count changes, the others on every operation, and itemId is only present on read and archived events. Remove the observer with the returned function or with removeObserver(listener).

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.

Consent, advertising ID, badge and location permissions

await Pushizo.login('user_42', { profile: { email: 'ali@example.com', sms: '+905321234567', tags: { plan: 'pro' } } });

await Pushizo.User.setAdsPersonalizationConsent(true);    // returns the current preferences (including consents)
const consents = await Pushizo.User.getConsents();        // [{ purpose, granted, source, updatedAt }]
Pushizo.Ads.setAdvertisingId(idfaOrGaid);                 // null deletes the record; your app obtains the ID

const shown = await Pushizo.Notifications.setBadgeCount(3); // Android: can the badge be shown; iOS: true
await Pushizo.Notifications.clearBadge();
const badge = await Pushizo.Notifications.getBadgeCount();

const granted = await Pushizo.Location.permissionGranted();
const always = await Pushizo.Location.backgroundPermissionGranted();
if (granted && !always) await Pushizo.Location.requestBackgroundPermission('We let you know when you are near a store.');

const ready = await Pushizo.isInitialized();
const live = await Pushizo.Chat.isListening();
await Pushizo.User.registerAdm(admRegistrationId);        // Fire OS; no-op on iOS

The profile in login (email, sms, tags, aliases) is set in the same call as the login; an invalid email or phone number is rejected with INVALID_ARGUMENT before logging in. setAdsPersonalizationConsent allows the user's hashed email/phone to be sent to ad platform audiences and false withdraws the consent; the advertising ID is only used while that consent exists and as a SHA-256 hash (the SDK ships no ad library and no ATT prompt). requestBackgroundPermission(rationale?) and requestAlwaysPermission() are the same permission: on Android ACCESS_BACKGROUND_LOCATION after a rationale dialog (false if it is missing from the manifest), on iOS the "always" permission (rationale is not used); get the foreground permission with requestPermission first. setBadgeCount and clearBadge return Promise<boolean> (awaiting is optional): on iOS the app badge and the counter shared with the notification service extension are set and the result is true; Android has no standard "set the badge" API, so the SDK stores the count and writes it to subsequent notifications, and the result is true when the badge can be shown on the device (false before Android 8 or when notifications or the channel badge are turned off). getBadgeCount() returns the stored count on Android and the icon badge on iOS. Calls that exist on one platform only never fail on the other: registerAdm is a no-op on iOS.

User properties, flag observer and the ready-made chat screen

await Pushizo.User.setProperty('plan', 'pro');             // string, number, boolean, array or plain object
await Pushizo.User.setProperty('plan', null);              // null deletes the property

const stop = Pushizo.FeatureFlags.addObserver(() => rerender()); // whenever values are refreshed from the server
stop();                                                    // or removeObserver(sameFunction)

Pushizo.Chat.show();                                       // ready-made chat screen
const open = await Pushizo.Chat.isPresented();
const closed = await Pushizo.Chat.hide();                  // true if a screen was open

The setProperty key is 1-64 characters; the value can be a string, a finite number, a boolean, or an array/plain object of those (nested null is not supported). Invalid input is rejected with a TypeError before the call and with INVALID_ARGUMENT by native validation; while offline the call waits in the native SDK queue. The flag observer is called at session start and after refresh() and carries no payload; read the current value with isEnabled / getValue. Chat.show() opens the full-screen HsChatActivity on Android and the modal HSChatViewController on iOS; no second screen is opened if one is already open, and nothing happens if initialize has not been called. Chat.isPresented() is read from the native SDK on iOS; the native Android SDK has no equivalent, so the bridge tracks the open screen through the Activity lifecycle.

Events (outcomes) and more

Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9); // the name also fires in-app event triggers
Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9, { eventId: 'order-1001' }); // deduplication ID
Pushizo.Notifications.clearAll();                           // Pushizo notifications (also resets the badge on iOS)
await Pushizo.Notifications.removeGroupedNotifications('orders'); // Android android_group / iOS thread-id
await Pushizo.Notifications.removeNotification(n.androidNotificationId!); // Android tray ID (null on iOS)
await Pushizo.Notifications.removeNotification('request-id');             // iOS: UNNotificationRequest.identifier
Pushizo.Debug.setLogLevel(LogLevel.Debug);                  // None | Error | Warn | Info | Debug

eventId is 8-64 characters (letters, digits and . _ : -): if you pass the same ID as your ad pixel or Conversions API event, the server counts the event once. If the format is invalid, the SDK generates its own ID.

Error codes

The code field of a promise rejection:

CodeMeaning
INVALID_ARGUMENTInvalid email/phone/alias/trigger/preference (local validation).
NOT_READYinitialize wasn't called, or the subscription isn't registered yet (notification inbox, preferences).
NO_ACTIVITYNo foreground Activity for the permission request on Android.
HS_…Server error code (e.g. HS_FORBIDDEN, HS_NOT_FOUND); catalog: Errors.
HS_ERRORUnclassified native error.

Empty/invalid arguments throw TypeError / RangeError before reaching the bridge.

Testing

cd sdk/react-native && npm install && npm run typecheck && npm test && npm run build
cd examples/react-native/android && ./gradlew :pushizo_react-native:compileDebugKotlin

Troubleshooting

SymptomCause / fix
"native module not found" error (on the first call)You're using Expo Go, pod install wasn't run on iOS, or the app wasn't rebuilt after installing the package (a Metro reload is not enough); use a development build and do a full rebuild.
No token on iOS, no subscription createdPushizo.setDeviceToken isn't forwarded in AppDelegate, or the Push Notifications capability is missing.
Tap is lost when opening from a notificationAdd the click listener early in the root component; provide the early-initialization meta-data/Info.plist keys.
Expo prebuild errormode is missing, or appId wasn't set while the NSE is enabled.
requestPermission always falsePermission denied on Android 13+ (must be enabled in settings); Push capability missing on iOS. Other symptoms: Android, iOS.

On this page