Local Notifications

Introduction

Nylo Website provides a local notification system through the LocalNotification class. This allows you to send immediate or scheduled notifications with rich content on iOS and Android.

Local notifications are not supported on the web. Attempting to use them on web will throw a NotificationException.

Basic Usage

Send a notification using the builder pattern or the static method:

import 'package:nylo_framework/nylo_framework.dart';

// Builder pattern
await LocalNotification(title: "Hello", body: "World").send();

// Using the helper function
await localNotification("Hello", "World").send();

// Using the static method
await LocalNotification.sendNotification(
  title: "Hello",
  body: "World",
);

Scheduled Notifications

Schedule a notification to be delivered at a specific time:

// Schedule for tomorrow
final tomorrow = DateTime.now().add(Duration(days: 1));

await LocalNotification(
  title: "Reminder",
  body: "Don't forget your appointment!",
).send(at: tomorrow);

// Using the static method
await LocalNotification.sendNotification(
  title: "Reminder",
  body: "Don't forget your appointment!",
  at: tomorrow,
);

Builder Pattern

The LocalNotification class provides a fluent builder API. All chainable methods return the LocalNotification instance:

await LocalNotification(title: "New Photo", body: "Check this out!")
    .addPayload("photo_id:123")
    .addId(42)
    .addSubtitle("From your friend")
    .addBadgeNumber(3)
    .addSound("custom_sound.wav")
    .send();

Chainable Methods

send()

Future<void> send({
  DateTime? at,
  AndroidScheduleMode? androidScheduleMode,
})

If at is provided, schedules the notification for that time. Otherwise shows it immediately.

Platform Configuration

In v7, platform-specific options are configured through AndroidNotificationConfig and IOSNotificationConfig objects.

Android Configuration

Pass an AndroidNotificationConfig to setAndroidConfig():

await LocalNotification(
  title: "Android Notification",
  body: "With custom configuration",
)
.setAndroidConfig(AndroidNotificationConfig(
  channelId: "custom_channel",
  channelName: "Custom Channel",
  channelDescription: "Notifications from custom channel",
  importance: Importance.max,
  priority: Priority.high,
  enableVibration: true,
  vibrationPattern: [0, 1000, 500, 1000],
  enableLights: true,
  ledColor: Color(0xFF00FF00),
))
.send();

AndroidNotificationConfig Properties

iOS Configuration

Pass an IOSNotificationConfig to setIOSConfig():

await LocalNotification(
  title: "iOS Notification",
  body: "With custom configuration",
)
.setIOSConfig(IOSNotificationConfig(
  presentAlert: true,
  presentBanner: true,
  presentSound: true,
  threadIdentifier: "thread_1",
  interruptionLevel: InterruptionLevel.active,
))
.addBadgeNumber(1)
.addSound("custom_sound.wav")
.send();

IOSNotificationConfig Properties

Attachments (iOS Only)

Add image, audio, or video attachments to iOS notifications. Attachments are downloaded from a URL:

await LocalNotification(
  title: "New Photo",
  body: "Check out this image!",
)
.addAttachment(
  "https://example.com/image.jpg",
  "photo.jpg",
  showThumbnail: true,
)
.send();

Managing Notifications

Cancel a Specific Notification

await LocalNotification.cancelNotification(42);

// With a tag (Android)
await LocalNotification.cancelNotification(42, tag: "my_tag");

Cancel All Notifications

await LocalNotification.cancelAllNotifications();

Clear Badge Count

await LocalNotification.clearBadgeCount();

Permissions

Request notification permissions from the user:

// Request with defaults
await LocalNotification.requestPermissions();

// Request with specific options
await LocalNotification.requestPermissions(
  alert: true,
  badge: true,
  sound: true,
  provisional: false,
  critical: false,
  vibrate: true,
  enableLights: true,
  channelId: 'default_notification_channel_id',
  channelName: 'Default Notification Channel',
);

Permissions are automatically requested on the first notification send via NyScheduler.taskOnce.

Platform Setup

iOS Setup

Add to your Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

Android Setup

Add to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.USE_FULL_SCREEN_INTENT" />

API Reference

Static Methods

Instance Methods (Chainable)