Awesome Notifications

The NotificationLocalization class allows you to provide localized strings for notification components like title, body, summary, largeIcon, bigPicture, and buttonLabels.

To use localization:

1. Use setLocalization(languageCode: '...') to set the active language (e.g., 'en', 'pt-br').
2. Use getLocalization() to retrieve the current language code.
3. When calling createNotification, pass a localizations map where keys are language codes and values are NotificationLocalization objects.

await AwesomeNotifications().createNotification(
  content: NotificationContent(
    id: id,
    channelKey: 'basic_channel',
    title: 'Default English Title',
    body: 'Default English Body',
    // ... other content fields
  ),
  localizations: {
    'pt-br' : NotificationLocalization(
        title: 'Este título está em português!',
        body: 'Corpo traduzido!',
        summary: 'Resumo em português',
        bigPicture: 'asset://assets/images/pt-br.jpg',
        largeIcon: 'asset://assets/images/brazilian.jpg',
        buttonLabels: {
          'AGREED1': 'Eu concordo!',
        }
    ),
  }
);

To schedule a notification, pass one of the following scheduling classes to the schedule property of the createNotification method:

• NotificationCalendar: Schedules a notification for when specific date components match. If a component (like second) is set to null, any value for that component is valid. Only one value per component is allowed.
• NotificationInterval: Schedules a notification to repeat at a specific time interval (e.g., every 60 seconds).
• NotificationAndroidCrontab: (Android only) Schedules notifications based on a crontab rule or a list of precise dates with second precision.

All scheduling classes support these properties:

• timeZone: The time zone for the schedule (e.g., "UTC", "America/Los_Angeles", "Europe/London").
• allowWhileIdle: Whether to send the notification even during low battery/critical device states.
• repeats: Whether the schedule should repeat after being displayed.

// Example: Interval scheduling
await AwesomeNotifications().createNotification(
  content: NotificationContent(
    id: 1,
    channelKey: 'scheduled',
    title: 'Every minute',
    body: 'Repeating notification',
  ),
  schedule: NotificationInterval(interval: 60, timeZone: localTimeZone, repeats: true),
);

You can customize how a user interacts with a notification by selecting an action type. For silent action types, always use the await keyword to prevent the Dart isolate from shutting down before the work completes.

Action Types

• Default: Forces the app to the foreground when the notification is tapped.
• SilentAction: Runs on the main thread without forcing the app to the foreground. Can accept visual elements. Can be interrupted if the main app is terminated.
• SilentBackgroundAction: Runs in a background exclusive Dart isolate without forcing the app to the foreground. Does not accept visual elements.
• KeepOnTop: Fires the action without closing the notification tray and without bringing the app to the foreground.
• DisabledAction: Closes the notification in the tray without firing an event.
• DismissAction: Dismisses the notification and fires onDismissActionReceivedMethod. Ignores the autoDismissible property.
• InputField (Deprecated): Use the requireInputText property instead to open a dialog for text responses.

Notification events are delivered only after calling the setListeners method. Note that events may not always be delivered at the exact moment they occur, depending on the app lifecycle and platform.

Available Event Methods

• onNotificationCreatedMethod (optional): Fires when a notification is created.
• onNotificationDisplayedMethod (optional): Fires when a notification is displayed on the system status bar.
• onActionReceivedMethod (required): Fires when a notification is tapped by the user. Note: This method fires immediately across all platforms and lifecycles.
• onDismissedActionReceivedMethod (optional): Fires when a notification is dismissed (subject to OS restrictions).

Delivery Conditions by Platform

When handling silentAction or silentBackgroundAction events, you may be running in a separate Dart Isolate that lacks a valid BuildContext. To perform UI operations (like navigation) in the main isolate, use IsolateNameServer with ReceivePort and SendPort.

Pattern:

1. Create a ReceivePort during initialization in the main isolate.
2. Register the port with a unique name using IsolateNameServer.registerPortWithName.
3. In your onActionReceivedMethod (which might run in a background isolate), check if you have access to the main isolate. If not, look up the SendPort by name and send the action data to it.
4. The listener on the ReceivePort in the main isolate then receives the data and performs the UI/navigation logic.

// 1. In your initialization (Main Isolate)
ReceivePort port = ReceivePort();
IsolateNameServer.registerPortWithName(port, 'notification_actions');
port.listen((var serializedData) async {
    final receivedAction = ReceivedAction().fromMap(serializedData);
    _handleActionReceived(receivedAction);
});

// 2. In your static listener (Background Isolate)
static Future<void> onActionReceivedMethod(ReceivedAction received) async {
  if (!_initialized) {
    SendPort? uiSendPort = IsolateNameServer.lookupPortByName('notification_actions');
    if (uiSendPort != null) {
      uiSendPort.send(received.toMap());
      return;
    }
  }
  await _handleActionReceived(received);
}