Customize Notifications

Customize how notifications appear and behave on iOS and Android platforms.

iOS Notification Options

By default, the Airship SDK will request Alert, Badge, and Sound notification options for remote notifications. You can customize these options by setting them before enabling user notifications:

Airship.push.iOS.setNotificationOptions([
  IOSNotificationOption.alert,
  IOSNotificationOption.badge,
  IOSNotificationOption.sound,
]);

// Then enable user notifications
await Airship.push.setUserNotificationsEnabled(true);

Available Options

• IOSNotificationOption.alert - Display alerts
• IOSNotificationOption.badge - Update the app badge
• IOSNotificationOption.sound - Play sounds
• IOSNotificationOption.carPlay - Display notifications in CarPlay
• IOSNotificationOption.criticalAlert - Display critical alerts (requires special entitlement)
• IOSNotificationOption.providesAppNotificationSettings - Indicates the app has custom notification settings
• IOSNotificationOption.provisional - Enables provisional authorization

Provisional Authorization

Apps can request provisional authorization along with the usual notification options. When requesting provisional authorization, apps do not need to prompt the user for permission initially, and notifications will be delivered in a non-interruptive manner to the Notification Center until the user explicitly chooses to keep delivering messages either prominently or quietly.

Airship.push.iOS.setNotificationOptions([
  IOSNotificationOption.alert,
  IOSNotificationOption.badge,
  IOSNotificationOption.sound,
  IOSNotificationOption.provisional,
]);

// Enable notifications (no prompt will be shown)
await Airship.push.setUserNotificationsEnabled(true);

iOS Foreground Presentation Options

When a push is received in the foreground on iOS, how the notification is displayed to the user is controlled by foreground presentation options. By default, the SDK will not set any options so the notification will be silenced.

Airship.push.iOS.setForegroundPresentationOptions([
  IOSForegroundPresentationOption.banner,
  IOSForegroundPresentationOption.list,
  IOSForegroundPresentationOption.sound,
]);

Available Presentation Options

• IOSForegroundPresentationOption.sound - Play the sound associated with the notification
• IOSForegroundPresentationOption.badge - Apply the notification’s badge value to the app’s icon
• IOSForegroundPresentationOption.list - Show the notification in Notification Center (and as a banner on iOS 13 and older)
• IOSForegroundPresentationOption.banner - Present the notification as a banner (and in Notification Center on iOS 13 and older)

iOS Badge Management

The badge on iOS presents a counter on top of the application icon. You can control this directly through Airship:

// Set badge number
await Airship.push.iOS.setBadge(20);

// Get current badge number
int currentBadge = await Airship.push.iOS.badge;
print('Current badge: $currentBadge');

// Reset badge
await Airship.push.iOS.resetBadge();

Auto-Badge

Auto-badge automatically increments the badge when a notification is received and decrements it when the notification is cleared:

// Enable auto-badge
await Airship.push.iOS.setAutoBadgeEnabled(true);

// Check if auto-badge is enabled
bool isEnabled = await Airship.push.iOS.isAutoBadgeEnabled();

iOS Authorized Notification Settings

Check which notification settings the user has authorized:

// Get authorized notification settings
List<IOSAuthorizedNotificationSetting> settings = 
    await Airship.push.iOS.authorizedNotificationSettings;

print('Authorized settings: $settings');

// Get authorization status
IOSAuthorizedNotificationStatus status = 
    await Airship.push.iOS.authorizedNotificationStatus;

print('Authorization status: $status');

Listen for changes to authorized settings:

Airship.push.iOS.onAuthorizedSettingsChanged.listen((event) {
  print('Authorized settings changed: ${event.authorizedSettings}');
});

Silent Notifications

Silent notifications are push messages that do not present a notification to the user. These are typically used to briefly wake the app from a background state to perform processing tasks or fetch remote content.

Platform-Specific Behavior

• Android: All push messages are delivered in the background. By default, Airship treats messages without an alert as silent.
• iOS: Set the content_available property to true in the iOS override object when sending the push.

Example Silent Notification Payload

{
  "audience": "all",
  "notification": {
    "ios": {
      "content_available": true,
      "extra": {
        "update_type": "content_refresh"
      }
    },
    "android": {
      "extra": {
        "update_type": "content_refresh"
      }
    }
  },
  "device_types": ["ios", "android"]
}

Clear Notifications

Clear notifications programmatically:

// Clear all notifications
await Airship.push.clearNotifications();

// Clear a specific notification by ID
await Airship.push.clearNotification('notification_id');

// Get active notifications
List<PushPayload> activeNotifications = await Airship.push.activeNotifications;
print('Active notifications: ${activeNotifications.length}');