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.x 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');

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?> where data contains a success or error message string.

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}');
  }
}

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.

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

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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?> where data contains a success or error message.

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, defaults to price if not set
    availability: TriggerAlertAvailabilityType.inStock, // optional, default for priceDrop
  );

  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, default for inventory
  );

  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?> where data contains a success or error message.

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 using the deepLinkStream stream.

Syntax​

get deepLinkStream

Returns​

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

Usage​

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

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.

Last updated on