PushizoDocs
SDK guides

Flutter SDK

pushizo_flutter — a plugin that wraps the native Android and iOS SDKs over MethodChannel/EventChannel; push, in-app (rendered with Flutter widgets), notification inbox, preferences.

pushizo_flutter wraps the native Android and iOS SDKs: HTTP, the queue, sessions, delivery feedback and trigger evaluation run on the native side; in-app messages are rendered with Flutter widgets. Web support is planned for v2. Example: examples/flutter-app.

Installation

# pubspec.yaml
dependencies:
  pushizo_flutter: ^0.1.0
  # From inside the monorepo: pushizo_flutter: { path: <repo>/sdk/flutter/pushizo_flutter }

Android

  1. google-services.json → android/app/; id("com.google.gms.google-services") version "4.4.2" apply false in android/settings.gradle.kts, id("com.google.gms.google-services") in android/app/build.gradle.kts.
  2. Dashboard → Channels → Android Push → service account JSON.
  3. If you build from inside the monorepo, add include(":pushizo") and project(":pushizo").projectDir = file("<repo>/sdk/android/pushizo") to the end of android/settings.gradle.kts; the published package uses the com.pushizo:pushizo-android artifact.

iOS

  1. ios/Podfile: platform :ios, '15.0'; cd ios && pod install.
  2. Xcode → Runner → Signing & Capabilities → Push Notifications, Background Modes → Remote notifications.
  3. Dashboard → Channels → iOS Push → .p8. The plugin picks up the APNs token automatically from UIApplicationDelegate events; no extra AppDelegate code is needed.
  4. For rich media and the received record, add a Notification Service Extension: iOS SDK.

Usage

import 'package:pushizo_flutter/pushizo_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Pushizo.initialize('app_…', apiUrl: 'https://api.pushizo.com', requiresPrivacyConsent: false, logLevel: PushizoLogLevel.warn);
  runApp(const MyApp());
}

await Pushizo.setConsentGiven(true);
final granted = await Pushizo.Notifications.requestPermission();
await Pushizo.login('user_42', identityHash: null);
await Pushizo.logout();

await Pushizo.User.addTags({'plan': 'pro'});  await Pushizo.User.removeTag('plan');
final tags = await Pushizo.User.getTags();     await Pushizo.User.setLanguage('tr');
final userId = await Pushizo.User.id;          final ext = await Pushizo.User.externalId;

final state = await Pushizo.User.pushSubscription.state; // id, token, optedIn, permission
await Pushizo.User.pushSubscription.optIn();  await Pushizo.User.pushSubscription.optOut();
Pushizo.User.pushSubscription.changes.listen((s) => …);

Pushizo.Notifications.clickStream.listen((e) => openRoute(e.url));      // e.notification, e.actionId
Pushizo.Notifications.foregroundStream.listen((n) => …);                // notification received in the foreground
final current = await Pushizo.Notifications.permission;
Pushizo.Notifications.permissionStream.listen((granted) => …);
Pushizo.Notifications.addPermissionObserver(onPermission);              // removePermissionObserver(onPermission)
await Pushizo.Session.sendEvent('purchase', properties: {'sku': 'A1'}, value: 49.9);
await Pushizo.Debug.setLogLevel(PushizoLogLevel.debug);

A tap received while the app was closed is delivered to the first clickStream listener (the native SDK holds it). Permission events arrive when a permission request completes and when the app returns to the foreground (if it was changed in settings); the initial state is not sent.

Email and SMS

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

User preferences

final prefs = await Pushizo.User.getPreferences();            // prefs.preferences, prefs.categories
for (final c in prefs.categories) print('${c.key}: ${c.localizedName('en')} (default ${c.defaultOptedIn})');
final updated = await Pushizo.User.setPreferences([
  const PushizoPreferenceInput(category: 'promos', optedIn: false),
  const PushizoPreferenceInput(category: 'orders', channel: 'android_push', optedIn: true),
]);

If there is no subscription yet you get PlatformException(NOT_READY); invalid input gives INVALID_ARGUMENT. Android notification channels (android_channels) are created by the native SDK; no extra Dart code is needed.

In-app messages

final navigatorKey = GlobalKey<NavigatorState>();
Pushizo.InAppMessages.setNavigatorKey(navigatorKey);   // MaterialApp(navigatorKey: navigatorKey); if omitted, the root navigator is looked up

await Pushizo.InAppMessages.addTrigger('level', 'gold'); // addTriggers, removeTrigger(s), clearTriggers, getTriggers
await Pushizo.InAppMessages.setScreen('cart');
await Pushizo.Session.sendEvent('cart_viewed');
await Pushizo.InAppMessages.setPaused(true);           // await Pushizo.InAppMessages.paused
Pushizo.InAppMessages.clickStream.listen((e) => …);    // e.messageId, e.actionId, e.url
Pushizo.InAppMessages.lifecycleStream.listen((e) => …); // e.type: willDisplay | didDisplay | willDismiss | didDismiss

The list, trigger evaluation, frequency, event logging and actions live in the native SDK; the selected message is rendered with Flutter widgets: modal/fullscreen → a transparent route (the back button and tapping outside close a dismissible message), banner_top/banner_bottom → an overlay (auto_dismiss_seconds). Colors default based on Theme.of(context).brightness.

Notification inbox

final page = await Pushizo.Inbox.list(limit: 20, cursor: null); // items, unreadCount, nextCursor, hasMore
final item = await Pushizo.Inbox.markRead(page.items.first.id);
final remaining = await Pushizo.Inbox.markAllRead();
await Pushizo.Inbox.archive(item.id);
final unread = await Pushizo.Inbox.unreadCount();

Errors are returned as PlatformException (NOT_READY: no subscription/user yet; or an API error code, e.g. HS_FORBIDDEN). Times are UTC DateTime.

Content cards

final feed = await Pushizo.ContentCards.list(limit: 20); // cards, unviewedCount
await Pushizo.ContentCards.logImpression(feed.cards.first.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). 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.

final 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
  final opened = await Pushizo.Delivery.showGuidance(); // ready-made dialog (22 languages); opens the settings screen if accepted
}
await Pushizo.Delivery.openSettings(setting: PushizoDeliverySetting.autoStart); // from your own UI

risk: none, elevated, high. Screens: auto, notifications, autoStart, batteryOptimization, appDetails. Change the interval with shouldShowGuidance(minIntervalDays: 30); the SDK never shows the dialog on its own. Android only: on iOS and the web status() returns supported: false and risk: none, and openSettings and showGuidance return false without doing anything.

Notification tray

await Pushizo.Notifications.clearAll();                          // Android: Pushizo notifications; iOS: all + badge
await Pushizo.Notifications.removeNotification(n.androidNotificationId!); // Android only
await Pushizo.Notifications.removeGroupedNotifications('orders'); // Android group key / iOS thread-id

Identity profile, consent, badge and location permission

The identity, consent, advertising ID, badge and location permission calls of the native Android and iOS SDKs are also available in Flutter. A call that only makes sense on one platform never throws on the others; it does nothing or returns false / an empty list.

// Login with a profile: an invalid email/phone is rejected before login (INVALID_ARGUMENT)
await Pushizo.login('user_42', profile: const PushizoUserProfile(email: 'ali@pushizo.com', sms: '+905321234567', tags: {'plan': 'pro'}));
final emails = await Pushizo.User.emails;           // smsNumbers; empty on the web
final ready = await Pushizo.isInitialized;

// Ads personalization consent and advertising ID
await Pushizo.User.setAdsPersonalizationConsent(true);   // returns the current preference list
final consents = await Pushizo.User.getConsents();        // purpose, granted, source, updatedAt
await Pushizo.Ads.setAdvertisingId(advertisingId);        // GAID / IDFA; null deletes the record

// Badge: the result tells whether the badge can be shown on this device
final shown = await Pushizo.Notifications.setBadgeCount(3);
await Pushizo.Notifications.clearBadge();
final badge = await Pushizo.Notifications.badgeCount;

// Location permission state and background permission (for geofencing)
if (await Pushizo.Location.permissionGranted && !await Pushizo.Location.backgroundPermissionGranted) {
  final granted = await Pushizo.Location.requestBackgroundPermission(rationale: 'We let you know when you are near a store.');
  if (granted) await Pushizo.Location.setGeofencingEnabled(true);
}

final listening = await Pushizo.Chat.isListening;         // is the live chat stream open
await Pushizo.User.registerAdm(admRegistrationId);        // Android only (Fire OS)

requestBackgroundPermission shows the rationale dialog and the system prompt on Android (the Settings screen on Android 11 and later) and asks for the "always" permission on iOS; requestAlwaysPermission() is the iOS name of the same call. It returns false when ACCESS_BACKGROUND_LOCATION is missing from the Android manifest. Your app obtains the advertising ID (the SDK ships no ads library and no ATT prompt); the ID is only used for users with the ads_personalization consent and as a SHA-256 hash.

On iOS the badge is written to the app icon and to the counter shared with the notification extension (true). Android has no standard "set the count" API for the launcher badge: the native SDK stores the count and writes it to the notifications it shows next; launchers that display a number use it, and no badge appears while the tray is empty. The result is false before Android 8, while notifications are disabled or when the user turned off the channel badge (the count is still stored). On the web the App Badging API is used (visible on installed PWAs); the result is false when the browser does not support it. badgeCount returns the stored count on Android, the app icon badge on iOS and the last value set in this session on the web.

On the web, login with a profile, the consent calls and Location.permissionGranted go to the Web SDK (the profile is validated before login). The advertising ID and ADM calls are no-ops on the web; the background location permission returns false.

User property, observers, event ID and ready-made chat

// User property: text, number, bool, or a list/map of those; null deletes the property
await Pushizo.User.setProperty('first_name', 'Ali');
await Pushizo.User.setProperty('first_name', null);

// Inbox observer (as a stream: Pushizo.Inbox.changes)
void onInbox(PushizoInboxChangeEvent e) => updateBadge(e.unreadCount); // type: listed, read, read_all, archived, count
Pushizo.Inbox.addObserver(onInbox);
Pushizo.Inbox.removeObserver(onInbox);

// Feature flag observer (as a stream: Pushizo.FeatureFlags.changes)
void onFlags() => rebuild();
Pushizo.FeatureFlags.addObserver(onFlags);
Pushizo.FeatureFlags.removeObserver(onFlags);

// Event deduplication ID: pass the same ID as your ad pixel and the server deduplicates the event
await Pushizo.Session.sendEvent('purchase', value: 49.9, eventId: 'order-1042');

// Ready-made chat screen
await Pushizo.Chat.show();
final open = await Pushizo.Chat.isPresented;
final closed = await Pushizo.Chat.hide();

The setProperty key must be 1-64 characters; an invalid key or an unsupported value throws ArgumentError before reaching the platform. While offline the property waits in the native SDK queue.

The inbox observer receives read, read_all and archived on every operation, and listed and count only when the unread count changed; itemId is set only for single-item events. The flag observer is called every time the values are refreshed from the server (session start and refresh()). The same observer is never added twice; observers receive the events that follow Pushizo.initialize.

eventId is 8-64 characters (letters, digits and . _ : -); when it is missing or malformed the SDK generates its own ID.

Chat.show() opens the native SDK chat screen on Android (HsChatActivity), the modal chat screen on iOS and the Web SDK chat widget on the web; hide() returns true when it closed an open screen. On Flutter web Chat.getConfig, getConversation, unreadCount, refreshUnreadCount, setTyping and attachmentUrl are forwarded to the Web SDK as well; the messaging methods (start, getMessages, sendMessage, sendAttachment, markRead, leaveOfflineMessage, startListening, stopListening, visitorId) return PLATFORM_NOT_SUPPORTED on the web, because messaging on the web is done through the chat widget.

Testing

cd sdk/flutter/pushizo_flutter && flutter analyze && flutter test
cd examples/flutter-app && flutter analyze && flutter build apk --debug

Troubleshooting

SymptomCause / fix
MissingPluginExceptionflutter clean && flutter pub get; fully rebuild the app (hot restart is not enough).
Android: project ':pushizo' not foundAdd the module to settings.gradle.kts or publish the SDK with publishToMavenLocal.
iOS: Pushizo pod not foundAdd the pod 'Pushizo' line to the Podfile and run pod install.
In-app message isn't renderedsetNavigatorKey wasn't set and no root navigator was found, or another message is open.
requestPermission always falsePermission denied on Android 13+; Push capability missing on iOS. Other symptoms: Android, iOS.

On this page