Skip to main content

Flutter SDK Reference

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

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

pub.dev GitHub release

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.

PropertyTypeDescription
firstNameObject?Subscriber's first name
lastNameObject?Subscriber's last name
emailObject?Email address
phoneObject?Phone number
genderObject?Gender
dobObject?Date of birth
languageObject?Locale/language code
profileIdObject?Your own user ID; numeric values are auto-coerced to string
countryObject?Country
cityObject?City
stateObject?State / region
zipObject?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.

PropertyTypeRequiredDescription
eventNameStringYesName of the event (e.g., "MySite.AddToCart"). Must be non-empty.
dataMap<String, Object>?NoCustom 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.
profileIdString?NoProfile ID of the subscriber.
providerString?NoProvider name. Defaults to "PushEngage" in the native SDK.
eventTypeString?NoEvent 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​

FieldTypeDescription
citystringSubscriber's city
statestringSubscriber's state or region
countrystringSubscriber's country
devicestringDevice name
device_typestringDevice type (e.g., mobile, tablet)
user_agentstringApp user agent string
hoststringHost identifier
timezonestringSubscriber's timezone
has_unsubscribedbooleanWhether the subscriber has unsubscribed
ts_createdstringISO 8601 timestamp of subscription creation
segmentsarraySegment 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}');
  }
}

In-App Messaging​

Display in-app messages authored on the PushEngage dashboard. Requires Flutter SDK 1.1.0+.

In-app messaging is a separate channel from push: it needs only an App ID, and works without a push subscription or notification permission. For trigger semantics, action types, frequency caps and troubleshooting, see the In-App Messaging guide.

triggerIAMEvent​

Reports a custom trigger event. Campaigns whose trigger event name matches, and whose trigger conditions the supplied parameters satisfy, are evaluated against their date window, frequency cap and audience rules, then displayed if eligible.

Campaigns with an app open trigger are fired by the SDK itself and need no call.

Syntax​

Dart
triggerIAMEvent(String eventName, [Map<String, dynamic>? parameters])

Parameters​

eventName: The trigger event name. Pass the exact string configured as the campaign's trigger event on the dashboard, including its casing. Required and must be non-empty — an empty name matches no campaign, so the call returns a failure result whose error is a PlatformException with code 400 and message Event name is required, rather than reporting a silent success. The plugin applies this check itself, so iOS and Android fail identically.

parameters (optional): Data used to evaluate the campaign's trigger conditions. Values are converted to string form before matching, so give numeric comparisons a number-typed condition on the dashboard — both sides are then parsed rather than compared as text. Parameters that no condition names are ignored. Use strings, numbers or booleans as values; other types aren't supported for matching.

Returns​

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

Success means the event was accepted for processing, not that a message was displayed.

Usage​

Dart
Future<void> reportAbandonedCart() async {
  PushEngageResult<String?> result = await PushEngage.triggerIAMEvent(
    'cart_abandoned',
    {'cart_value': 120, 'currency': 'USD'},
  );

  if (!result.isSuccess) {
    print('Failed to trigger in-app message: ${result.error}');
  }
}

onIAMCustomAction​

A broadcast stream that emits when the user taps a custom action button inside a displayed message.

The SDK handles Open URL, Dismiss and Request notification permission buttons itself — only Custom action buttons reach this stream. The message is dismissed after the action is forwarded. The SDK doesn't act on a custom action itself; to open a link, use an Open URL action instead.

If nothing is listening, a custom button tap is still recorded as a click and still closes the message.

Syntax​

Dart
static Stream<IAMCustomAction> get onIAMCustomAction

The IAMCustomAction model:

FieldTypeDescription
actionIdStringInternal button key generated by the dashboard (e.g. t04B05). Don't route on it.
parametersMap<String, String>Parameters attached to the action. parameters['action'] holds the dashboard Action name, so route on it. Values are always Strings.

Usage​

Dart
StreamSubscription<IAMCustomAction>? _customActionSub;

@override
void initState() {
  super.initState();
  _customActionSub = PushEngage.onIAMCustomAction.listen((action) {
    switch (action.parameters['action']) {
      case 'view_cart':
        Navigator.of(context).pushNamed('/cart');
        break;
      case 'open_offers':
        Navigator.of(context).pushNamed('/offers');
        break;
    }
  });
}

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

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:

CodeMeaning
5001FCM_SENDER_ID_MISMATCH — google-services.json sender ID does not match the dashboard.
5002FCM_PROJECT_ID_MISMATCH — google-services.json project ID does not match the service-account JSON.
5003FCM_LOCAL_CONFIG_INVALID — Firebase Installations rejected google-services.json as invalid for the app.
5004FCM_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();
}
Last updated on