Flutter SDK Reference

Complete API reference for the PushEngage Flutter SDK. For setup and installation, see the Flutter Quickstart.

The SDK supports Flutter 3.x and above. It uses FCM for Android and APNs for iOS.

Initialization

setAppId

Sets the application ID for PushEngage. This method sets the application ID for your PushEngage integration.

Syntax

setAppId(String appId)

Parameters

appId: The application ID to be set for PushEngage integration.

Usage

Dart

await PushEngage.setAppId('your_app_id_here');

setEnvironment

Switch the SDK between the staging and production backends. This is intended for internal testing against the PushEngage staging environment — most apps should leave the default (production) untouched.

Call before setAppId

setEnvironment must be invoked before setAppId. The native Android SDK caches its base URLs when the app id is set, and switching the environment after initialization is unsupported.

Syntax

setEnvironment(Environment environment)

Parameters

environment: Environment.staging or Environment.production.

Usage

Dart

import 'package:pushengage_flutter_sdk/model/environment.dart';

await PushEngage.setEnvironment(Environment.production);
await PushEngage.setAppId('YOUR_APP_ID');

Notification Permission

requestNotificationPermission

Requests notification permission from the user. For Android 13 (API 33) and above, this will show the system permission dialog. For older versions, the permission is automatically granted.

Syntax

requestNotificationPermission()

Returns

A PushEngageResult<bool> containing a boolean value indicating whether the permission was granted or not. The result includes success/error status and the permission state.

Usage

Dart

PushEngageResult<bool> result = await PushEngage.requestNotificationPermission();

if (result.isSuccess) {
  bool isGranted = result.data ?? false;
  print('Permission granted: $isGranted');
} else {
  print('Error requesting permission: ${result.error}');
}

getNotificationPermissionStatus

Get the current notification permission status for the application.

Syntax

getNotificationPermissionStatus() -> Future<PushEngageResult<String>>

Returns

A PushEngageResult<String> containing a string indicating the current notification permission state:

• "granted": The application is authorized to post user notifications
• "denied": The application is not authorized to post user notifications

Usage

Dart

PushEngageResult<String> result = await PushEngage.getNotificationPermissionStatus();

if (result.isSuccess) {
  String status = result.data ?? '';
  if (status == 'granted') {
    print('Notifications are enabled');
  } else {
    print('Notifications are disabled');
  }
} else {
  print('Error getting permission status: ${result.error}');
}

Subscription

subscribe

Subscribe the user to push notifications. This method checks the current permission status and subscription state to determine the appropriate action. If notification permission is not granted, it will automatically request permission first.

Syntax

subscribe()

Returns

A PushEngageResult<bool> containing:

• true: Subscribe operation completed successfully
• false: Subscribe operation failed

Usage

Dart

PushEngageResult<bool> result = await PushEngage.subscribe();

if (result.isSuccess) {
  bool success = result.data ?? false;
  if (success) {
    print('User subscribed successfully');
  } else {
    print('Subscribe operation failed');
  }
} else {
  print('Error subscribing user: ${result.error}');
}

unsubscribe

Unsubscribe the user from push notifications. This stops the user from receiving notifications but keeps their profile and preferences in the system. The user can be re-subscribed later using the subscribe() method.

Syntax

unsubscribe()

Returns

A PushEngageResult<bool> containing:

• true: Unsubscribe operation completed successfully
• false: Unsubscribe operation failed

Usage

Dart

PushEngageResult<bool> result = await PushEngage.unsubscribe();

if (result.isSuccess) {
  bool success = result.data ?? false;
  if (success) {
    print('User unsubscribed successfully');
  } else {
    print('Unsubscribe operation failed');
  }
} else {
  print('Error unsubscribing user: ${result.error}');
}

getSubscriptionStatus

Check whether the user is currently subscribed to push notifications.

Syntax

getSubscriptionStatus()

Returns

A PushEngageResult<bool> containing a boolean value indicating the subscription status:

• true: User is subscribed to push notifications
• false: User is not subscribed (unsubscribed or never subscribed)

Usage

Dart

PushEngageResult<bool> result = await PushEngage.getSubscriptionStatus();

if (result.isSuccess) {
  bool isSubscribed = result.data ?? false;
  if (isSubscribed) {
    print('User is subscribed to push notifications');
  } else {
    print('User is not subscribed to push notifications');
  }
} else {
  print('Error getting subscription status: ${result.error}');
}

getSubscriptionNotificationStatus

Check whether the user can actually receive push notifications by verifying both subscription status and notification permission. The user can receive notifications only if they are subscribed AND the app has notification permission granted.

Syntax

getSubscriptionNotificationStatus()

Returns

A PushEngageResult<bool> containing a boolean value indicating the complete notification capability:

• true: User can receive notifications (subscribed AND permission granted)
• false: User cannot receive notifications (not subscribed or permission denied)

Usage

Dart

PushEngageResult<bool> result = await PushEngage.getSubscriptionNotificationStatus();

if (result.isSuccess) {
  bool canReceiveNotifications = result.data ?? false;
  if (canReceiveNotifications) {
    print('User can receive push notifications');
  } else {
    print('User cannot receive push notifications');
  }
} else {
  print('Error getting notification capability: ${result.error}');
}

Associate Profile ID

Profile IDs serve as unique identifiers for your subscribers, enabling you to recognize them across multiple devices. Each subscriber can be assigned just one profile ID. This ID should be a string, and you have the flexibility to use any value, such as an email or phone number.

getSubscriberId

Retrieve the unique subscriber ID for a user. PushEngage generates this ID for every user based on their subscription data. The subscriber ID remains consistent unless there's a change in the user's subscription. If the user is not subscribed, it will return null.

Syntax

getSubscriberId()

Returns

A PushEngageResult<String?> containing:

• String: The subscriber ID if the user is subscribed and has a valid hash
• null: If the user is not subscribed or doesn't have a valid hash

Usage

Dart

PushEngageResult<String?> result = await PushEngage.getSubscriberId();

if (result.isSuccess) {
  String? subscriberId = result.data;
  if (subscriberId != null) {
    print('Subscriber ID: $subscriberId');
  } else {
    print('User is not subscribed or no valid ID available');
  }
} else {
  print('Error getting subscriber ID: ${result.error}');
}

addProfileId

This method allows you to set a profile ID for the current subscriber. If a profile ID already exists, it will be replaced with the new value.

Syntax

Dart

addProfileId(String profileId)

Parameters

profileId: A string representing the unique profile ID to be assigned to the subscriber.

• Used to identify the subscriber across multiple devices.
• Can be any unique identifier like email, user ID, or phone number.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> addProfile() async {
  PushEngageResult<String?> result = await PushEngage.addProfileId('your_profile_id');

  if (result.isSuccess) {
    print('Profile ID added successfully: ${result.data}');
  } else {
    print('Failed to add profile ID: ${result.error}');
  }
}

User Identity

The identify and logout methods manage the predefined personal-data fields stored on the current subscriber. Use them to tie a push subscription to your own first-party user data and to clear that data on sign-out without unsubscribing the device.

The 12 valid keys are: first_name, last_name, email, phone, gender, dob, language, profile_id, country, city, state, zip. Values must be String, num, or bool — other types are rejected by the native layer.

identify

Upsert one or more of the 12 predefined subscriber fields. Repeat calls with the same payload short-circuit locally and resolve without a network round-trip, as long as the cache is fresh (within 24 hours of the last successful sync).

Syntax

identify(IdentifyFields fields)

Parameters

fields: An IdentifyFields object. Only the properties you set are sent; null properties are omitted. At least one non-null property is required.

Property	Type	Description
firstName	Object?	Subscriber's first name
lastName	Object?	Subscriber's last name
email	Object?	Email address
phone	Object?	Phone number
gender	Object?	Gender
dob	Object?	Date of birth
language	Object?	Locale/language code
profileId	Object?	Your own user ID; numeric values are auto-coerced to string
country	Object?	Country
city	Object?	City
state	Object?	State / region
zip	Object?	Postal code

Returns

A PushEngageResult<String?> containing the native success message, or the error on failure.

Usage

Dart

import 'package:pushengage_flutter_sdk/model/identify_fields.dart';

final fields = IdentifyFields(
  firstName: 'Jane',
  lastName: 'Doe',
  email: '[email protected]',
  profileId: 'user_12345',
);

final result = await PushEngage.identify(fields);

if (result.isSuccess) {
  print('Subscriber fields updated');
} else {
  print('Identify failed: ${result.error}');
}

logout

Remove a set of predefined personal fields from the current subscriber while keeping the device subscribed for push. Call this when a user signs out of your app to detach their PII from the push subscription.

Passing null or an empty list removes the default PII field set: first_name, last_name, email, phone, gender, dob, profile_id. Passing a list of field names scopes the removal to those specific fields. If none of the requested field names are currently cached locally (and the cache is fresh — within 24 hours of the last successful sync), the call resolves without a network request.

Syntax

logout(List<String>? fieldNames)

Parameters

fieldNames: An optional list of field names to remove. Pass null or an empty list to clear the default PII set.

Returns

A PushEngageResult<String?> containing the native success message, or the error on failure.

Usage

Dart

// Clear the default PII set
await PushEngage.logout(null);

// Clear specific fields
await PushEngage.logout(['email', 'phone']);

Custom Events

trackEvent

Track a custom event for the current subscriber. Custom events are used to start or exit campaign workflows based on in-app activity — for example, adding an item to cart, completing a purchase, or any other action you define. Workflows are configured from the PushEngage Dashboard.

Syntax

trackEvent(TrackEventPayload event)

Parameters

event: A TrackEventPayload describing the event.

Property	Type	Required	Description
eventName	String	Yes	Name of the event (e.g., "MySite.AddToCart"). Must be non-empty.
data	Map<String, Object>?	No	Custom key-value data. Values should be strings, numbers, or booleans; the Flutter layer does not validate them, so other types may be dropped or rejected by the backend.
profileId	String?	No	Profile ID of the subscriber.
provider	String?	No	Provider name. Defaults to "PushEngage" in the native SDK.
eventType	String?	No	Event type. Defaults to "PushEngage.CustomEvent" in the native SDK.

Returns

A PushEngageResult<String?> containing the native success message, or the error on failure.

Usage

Dart

import 'package:pushengage_flutter_sdk/model/track_event_payload.dart';

final event = TrackEventPayload(
  eventName: 'MySite.AddToCart',
  data: {
    'product_id': '123',
    'product_name': 'Product Name',
    'price': 49.99,
  },
);

final result = await PushEngage.trackEvent(event);

if (result.isSuccess) {
  print('Event tracked');
} else {
  print('Failed to track event: ${result.error}');
}

Subscriber Details

getSubscriberDetails

This method retrieves subscriber details based on a provided list of strings, which can include city, state, country, device, device type, segments, etc.

Syntax

Dart

getSubscriberDetails(List<String>? values)

Parameters

values: A list of strings specifying which subscriber fields to retrieve. See the Available Fields table below for all valid keys. Pass null to request all available fields (behavior is platform-dependent — see the note below).

• Specify which subscriber details you want to retrieve.
• Can include fields like city, state, country, device type, segments, etc.

Fetching all fields is platform-dependent

Pass null to request all fields. On iOS, this omits the query parameter and reliably returns the complete record. On Android, a null or empty list is sent as an empty ?fields= query parameter (the plugin treats the two the same), so whether all fields are returned depends on the backend accepting it.

Returns a failure when not subscribed

getSubscriberDetails resolves with a failure if the user is not currently subscribed (consistent across iOS, Android, and the underlying native SDKs).

Returns

A PushEngageResult<Map<String, dynamic>?> where data contains a map of the requested subscriber fields, or null if no data is available.

Usage

Dart

Future<void> fetchSubscriberDetails() async {
  final List<String> keys = [
    'city', 'device', 'host', 'user_agent',
    'has_unsubscribed', 'device_type', 'timezone',
    'country', 'ts_created', 'state',
  ];

  PushEngageResult<Map<String, dynamic>?> result =
      await PushEngage.getSubscriberDetails(keys);

  if (result.isSuccess) {
    print('City: ${result.data?['city']}');
    print('Country: ${result.data?['country']}');
  } else {
    print('Failed to get subscriber details: ${result.error}');
  }
}

Available Fields

Field	Type	Description
city	string	Subscriber's city
state	string	Subscriber's state or region
country	string	Subscriber's country
device	string	Device name
device_type	string	Device type (e.g., mobile, tablet)
user_agent	string	App user agent string
host	string	Host identifier
timezone	string	Subscriber's timezone
has_unsubscribed	boolean	Whether the subscriber has unsubscribed
ts_created	string	ISO 8601 timestamp of subscription creation
segments	array	Segment IDs the subscriber belongs to

Segments

Segments are used to group subscribers so that you can send personalized notifications. Segments can be created based on attributes, categories, and more.

addSegment

This method enables you to add the current subscriber to segments.

Syntax

Dart

addSegment(List<String> segments)

Parameters

segments: A list of segment IDs to be added.

• Contains the IDs of segments you want to add the subscriber to.
• Each segment ID should be a valid string identifier from your PushEngage dashboard.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> addSegments() async {
  PushEngageResult<String?> result =
      await PushEngage.addSegment(['segment1', 'segment2', 'segment3']);

  if (result.isSuccess) {
    print('Segments added: ${result.data}');
  } else {
    print('Failed to add segments: ${result.error}');
  }
}

addDynamicSegment

This method enables you to add the current subscriber to a segment for a specified duration, measured in days. After this period, the segment will be automatically removed from the subscriber.

Syntax

Dart

addDynamicSegment(List<DynamicSegment> segments)

Parameters

segments: A list of segment objects representing dynamic segments to be added.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> addDynamicSegments() async {
  final segments = [
    DynamicSegment(name: 'segment1', duration: 5),
    DynamicSegment(name: 'segment2', duration: 7),
  ];

  PushEngageResult<String?> result =
      await PushEngage.addDynamicSegment(segments);

  if (result.isSuccess) {
    print('Dynamic segments added: ${result.data}');
  } else {
    print('Failed to add dynamic segments: ${result.error}');
  }
}

removeSegment

This method allows you to remove the current subscriber from segments.

Syntax

Dart

removeSegment(List<String> segments)

Parameters

segments: A list of segment IDs to be removed.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> removeSegments() async {
  PushEngageResult<String?> result =
      await PushEngage.removeSegment(['segment1', 'segment2', 'segment3']);

  if (result.isSuccess) {
    print('Segments removed: ${result.data}');
  } else {
    print('Failed to remove segments: ${result.error}');
  }
}

Attributes

Attributes are key-value pairs that allow you to store additional information about your subscribers. You can utilize attributes to segment your subscribers and send personalized notifications.

addSubscriberAttributes

Use this method to add or update attributes for a subscriber. If an attribute with the specified key already exists, the existing value will be replaced.

Syntax

Dart

addSubscriberAttributes(Map<String, dynamic> attributes)

Parameters

attributes: A Map<String, dynamic> containing the subscriber attributes to be added.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> addAttributes() async {
  PushEngageResult<String?> result = await PushEngage.addSubscriberAttributes({
    'age': 25,
    'height': '6.1',
  });

  if (result.isSuccess) {
    print('Attributes added: ${result.data}');
  } else {
    print('Failed to add attributes: ${result.error}');
  }
}

setSubscriberAttributes

This method allows you to set attributes for a subscriber, replacing any previously associated attributes. Use this method when you need to entirely reset the attributes with new values.

Syntax

Dart

setSubscriberAttributes(Map<String, dynamic> attributes)

Parameters

attributes: A Map<String, dynamic> containing the updated subscriber attributes.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> setAttributes() async {
  PushEngageResult<String?> result = await PushEngage.setSubscriberAttributes({
    'age': 25,
    'height': '6.1',
  });

  if (result.isSuccess) {
    print('Attributes set: ${result.data}');
  } else {
    print('Failed to set attributes: ${result.error}');
  }
}

getSubscriberAttributes

Retrieve the attributes associated with the current subscriber using this method.

Syntax

Dart

getSubscriberAttributes()

Returns

A PushEngageResult<Map<String, dynamic>> where data contains all custom attributes set on the subscriber.

Usage

Dart

Future<void> fetchAttributes() async {
  PushEngageResult<Map<String, dynamic>> result =
      await PushEngage.getSubscriberAttributes();

  if (result.isSuccess) {
    print('Subscriber attributes: ${result.data}');
  } else {
    print('Failed to get attributes: ${result.error}');
  }
}

deleteSubscriberAttributes

This method allows you to remove one or more attributes from the current subscriber. Provide an array of attribute names you wish to remove. Passing an empty array will result in the removal of all the subscriber's attributes.

Syntax

Dart

deleteSubscriberAttributes(List<String> attributes)

Parameters

attributes: A List<String> containing attribute names to be deleted.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> deleteAttributes() async {
  PushEngageResult<String?> result =
      await PushEngage.deleteSubscriberAttributes(['age', 'height']);

  if (result.isSuccess) {
    print('Attributes deleted: ${result.data}');
  } else {
    print('Failed to delete attributes: ${result.error}');
  }
}

Automated Notifications

Automated notifications include all types of triggered campaigns, such as cart abandonment, price drop, back in stock, and browse abandonment. By default, automated notifications are enabled for all subscribers.

automatedNotification

This method allows you to enable/disable automated notifications for the current subscriber.

Syntax

Dart

automatedNotification(TriggerStatusType status)

Parameters

status: The trigger status type indicating the status of the trigger campaign.

• Use TriggerStatusType.enabled to enable automated notifications.
• Use TriggerStatusType.disabled to disable automated notifications.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Enable Automated Notifications

Dart

Future<void> enableAutomatedNotifications() async {
  PushEngageResult<String?> result =
      await PushEngage.automatedNotification(TriggerStatusType.enabled);

  if (result.isSuccess) {
    print('Automated notifications enabled: ${result.data}');
  } else {
    print('Failed to enable: ${result.error}');
  }
}

Disable Automated Notifications

Dart

Future<void> disableAutomatedNotifications() async {
  PushEngageResult<String?> result =
      await PushEngage.automatedNotification(TriggerStatusType.disabled);

  if (result.isSuccess) {
    print('Automated notifications disabled: ${result.data}');
  } else {
    print('Failed to disable: ${result.error}');
  }
}

Triggered Campaigns

sendTriggerEvent

Detect your visitor's behavior to send automated push notifications to the right person at the right time.

Syntax

Dart

sendTriggerEvent(TriggerCampaign trigger)

Parameters

trigger: The TriggerCampaign object representing the campaign event to be triggered.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> sendCampaignEvent() async {
  final trigger = TriggerCampaign(
    campaignName: 'Welcome Campaign',
    eventName: 'start',
    referenceId: '12345',         // optional
    profileId: 'user_67890',      // optional
    data: {'key1': 'value1'},     // optional
  );

  PushEngageResult<String?> result =
      await PushEngage.sendTriggerEvent(trigger);

  if (result.isSuccess) {
    print('Trigger event sent: ${result.data}');
  } else {
    print('Failed to send trigger: ${result.error}');
  }
}

addAlert

Re-engage your customers and increase conversion using Price Drop Alert Campaigns and Inventory Alert Campaigns.

Syntax

Dart

addAlert(TriggerAlert alert)

Parameters

alert: The TriggerAlert object representing the alert to be added.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Price Drop

Dart

Future<void> addPriceDropAlert() async {
  final alert = TriggerAlert(
    type: TriggerAlertType.priceDrop,
    productId: 'product_id',
    link: 'https://example.com/product/product_id',
    price: 100.0,
    alertPrice: 89.99,  // optional: target price; omitted when null (server may apply a default)
    availability: TriggerAlertAvailabilityType.inStock, // optional; omitted when null (server may apply a default)
  );

  PushEngageResult<String?> result = await PushEngage.addAlert(alert);

  if (result.isSuccess) {
    print('Price drop alert added: ${result.data}');
  } else {
    print('Failed to add alert: ${result.error}');
  }
}

Back in Stock Alert

Dart

Future<void> addInventoryAlert() async {
  final alert = TriggerAlert(
    type: TriggerAlertType.inventory,
    productId: 'product_id',
    link: 'https://example.com/product/product_id',
    price: 100.0,
    availability: TriggerAlertAvailabilityType.outOfStock, // optional; omitted when null (server may apply a default)
  );

  PushEngageResult<String?> result = await PushEngage.addAlert(alert);

  if (result.isSuccess) {
    print('Inventory alert added: ${result.data}');
  } else {
    print('Failed to add alert: ${result.error}');
  }
}

Goal Tracking

sendGoal

Goal Tracking will help you assign conversion goals and value to your notification campaigns. You can set up a default goal and have it integrated for all your campaigns.

Syntax

Dart

sendGoal(Goal goal)

Parameters

goal: Goal object representing the goal to be tracked.

Returns

A PushEngageResult<String?> — on success, data holds the native success message; on failure, data is null and error holds the exception (isSuccess == false).

Usage

Dart

Future<void> trackGoal() async {
  final goal = Goal(name: 'purchase', count: 1, value: 10.0);

  PushEngageResult<String?> result = await PushEngage.sendGoal(goal);

  if (result.isSuccess) {
    print('Goal tracked: ${result.data}');
  } else {
    print('Failed to track goal: ${result.error}');
  }
}

Deep Linking

deepLinkStream

Handle deep links in your Flutter app by listening to the deepLinkStream stream. The stream emits when a notification is tapped while the app is running. Cold-boot taps (notification taps that launch the app from a terminated state on iOS) are not delivered here — use getInitialNotification for those.

Syntax

get deepLinkStream

Returns

The stream emits a Map<String, dynamic> containing the deep link data:

{
  'deepLink': String,
  'data': Map<String, dynamic>,
}

Breaking change in 1.0.0

data is now always delivered as a Map on both platforms. On Android the SDK previously delivered data as a JSON-encoded string — if you were decoding it manually, remove that step.

Usage

Dart

PushEngage.deepLinkStream.listen((data) {
   if (data != null) {
     print('Received deep link data: $data');
   } else {
     print('No deep link data received.');
   }
 });

getInitialNotification

Recover the notification that cold-launched the app from a terminated state. On iOS, deepLinkStream only emits for taps that happen after Dart can subscribe, so the first cold-boot tap is missed. getInitialNotification is the pull-based companion — call it once on startup (in addition to listening on deepLinkStream) and the SDK delivers the buffered cold-boot tap.

iOS only

This method resolves with null on Android. Cold-boot deep links on Android flow through the host activity's intent filter and are not buffered by the SDK.

Syntax

getInitialNotification()

Returns

A PushEngageResult<Map<String, dynamic>?> containing:

• The cold-boot deep link payload ({'deepLink': String, 'data': Map<String, dynamic>}) on iOS, when one was buffered.
• null — when there was no cold-boot tap to recover (warm-boot launches, the app was already running, repeated calls after the buffered value was consumed, or Android).

The buffered value is consumed by the first successful call; subsequent calls resolve null.

Usage

Dart

@override
void initState() {
  super.initState();
  _readInitialNotification();
}

Future<void> _readInitialNotification() async {
  final result = await PushEngage.getInitialNotification();
  if (result.isSuccess && result.data != null) {
    print('Cold-boot deep link: ${result.data!['deepLink']}');
    // Navigate based on result.data['deepLink'] / result.data['data']
  }
}

Utilities

enableLogging

Enables or disables verbose debug logging for the SDK. When enabled, the SDK prints diagnostic output to the console.

danger

Set enableLogging to false before releasing to production to avoid leaking internal SDK state to device logs.

Syntax

Dart

enableLogging(bool shouldEnable)

Parameters

shouldEnable: Pass true to turn on debug logging, false to turn it off.

Usage

Dart

// Enable during development
PushEngage.enableLogging(true);

// Disable for production
PushEngage.enableLogging(false);

getSdkVersion

Retrieves the current version of the PushEngage Flutter Plugin, returning a string that represents the Plugin's current version.

Syntax

Dart

getSdkVersion()

Returns

A String representing the current version of the PushEngage Flutter Plugin.

Usage

Dart

PushEngage.getSdkVersion();

setSmallIconResource

Sets the resource name of the small icon used for notifications. The small icon appears in the status bar when a notification is displayed.

Syntax

Dart

setSmallIconResource(String resourceName)

Parameters

resourceName: A string representing the resource name of the small icon.

• Must be a valid Android drawable resource name.
• Used to display a custom small icon in push notifications.

Usage

Dart

void main() async {
  String resourceName = "your_small_icon_name";
  await PushEngage.setSmallIconResource(resourceName);
}

note

It is recommended to set a valid resource name to ensure proper display of notifications. If an invalid resource name is provided, the default bell icon specified by the PushEngage library will be used.

Android only

This method only applies on Android. On iOS, the call is a no-op — iOS notification icons are configured via the app's asset catalog and Notification Service Extension.

setBadgeCount

Set the app icon badge count.

• iOS: Sets the launcher icon badge directly. Uses UNUserNotificationCenter.setBadgeCount on iOS 16+, with applicationIconBadgeNumber fallback on older versions.
• Android: Stores the value and applies it to notifications the SDK builds afterwards. Android has no system API for a numeric launcher-icon badge — the count surfaces in the long-press shortcut menu. Passing 0 additionally clears all active notifications (via NotificationManagerCompat.cancelAll()), dismissing the app's entire notification tray.

Values outside the 32-bit signed integer range are coerced to 0 (badge cleared). Negative values within the Int32 range pass through to native, where Android treats them as 0 (cleared).

Syntax

setBadgeCount(int count)

Parameters

count: The badge count to set. Pass 0 to clear the badge.

Usage

Dart

// Set the badge
await PushEngage.setBadgeCount(5);

// Clear the badge
await PushEngage.setBadgeCount(0);

Diagnostics (Android)

The methods in this section are Android-only — they help diagnose Firebase Cloud Messaging configuration drift between the device's google-services.json and the configuration registered on the PushEngage dashboard. iOS calls resolve as no-ops so cross-platform code can call them unconditionally.

runConfigValidation

Re-run the SDK's FCM configuration validator. Mismatch details are delivered asynchronously through onFcmConfigError, not via the return value. Always resolves true on iOS (no FCM surface).

Syntax

runConfigValidation(String senderId, String projectId)

Parameters

senderId: The Firebase sender ID expected by your PushEngage site.

projectId: The Firebase project ID expected by your PushEngage site.

Returns

A PushEngageResult<bool>:

• true — the configuration matches, the check was skipped (Firebase not yet initialized), or the call was a no-op on iOS.
• false — a mismatch was detected (sender ID, project ID, or both).

The specific mismatch details are also delivered asynchronously through onFcmConfigError. If the validator itself throws, the call resolves as a failure result (CONFIG_VALIDATION_ERROR) — it never returns false to signal "could not run".

Usage

Dart

final result = await PushEngage.runConfigValidation('1234567890', 'my-firebase-project');
if (result.isSuccess) {
  print('Config validation dispatched: ${result.data}');
}

onFcmConfigError

A stream of Firebase Cloud Messaging configuration errors emitted by the Android native SDK. Common causes are sender-ID or project-ID mismatches between google-services.json and the PushEngage dashboard.

The Android error codes are:

Code	Meaning
5001	FCM_SENDER_ID_MISMATCH — google-services.json sender ID does not match the dashboard.
5002	FCM_PROJECT_ID_MISMATCH — google-services.json project ID does not match the service-account JSON.
5003	FCM_LOCAL_CONFIG_INVALID — Firebase Installations rejected google-services.json as invalid for the app.
5004	FCM_CONFIG_BOTH_MISMATCH — both sender ID and project ID differ from the dashboard configuration.

iOS no-op

The native iOS bridge does not emit FCM config errors. Listening on iOS is harmless and simply never fires.

Syntax

get onFcmConfigError

Returns

A Stream<FcmConfigError>. The FcmConfigError model has two fields:

class FcmConfigError {
  final int code;
  final String message;
}

Usage

Dart

import 'package:pushengage_flutter_sdk/model/fcm_config_error.dart';

late StreamSubscription<FcmConfigError> _fcmErrorSub;

@override
void initState() {
  super.initState();
  _fcmErrorSub = PushEngage.onFcmConfigError.listen((error) {
    print('FCM config error ${error.code}: ${error.message}');
  });
}

@override
void dispose() {
  _fcmErrorSub.cancel();
  super.dispose();
}