Foreground Notifications

Overview

Foreground notifications in iOS allow apps to display notifications while they are active. These notifications ensure that important updates are delivered without moving the app to the background.

Use Case

1. Purpose:

   • Display real-time updates, alerts, or actions while the app is being used.

   • Provide a seamless and engaging user experience with in-app notifications.

2. Benefits:

   • Ensure visibility of important updates during app usage.

   • Allow users to respond to notifications without switching context.

Implementation Details

How you control foreground notifications depends on who owns the delegate of UNUserNotificationCenter: the SDK or your app.

SDK Owns the Delegate

With the Basic Automated Setup, the SDK is the delegate and decides whether a notification is shown in the foreground. Control this with the showNotificationsOnForeground property. Its default value is false, so notifications are not shown while the app is in the foreground.

Appoxee.shared()?.showNotificationsOnForeground = true

[Appoxee shared].showNotificationsOnForeground = YES;

App Owns the Delegate

If your app sets itself as the delegate, it takes over userNotificationCenter(_:willPresent:withCompletionHandler:) and must return the presentation options itself. The SDK has no method to forward willPresent to. In this case, setting showNotificationsOnForeground alone has no effect.

The following example reads showNotificationsOnForeground, so you can still control foreground display through this property. When the flag is false, the example returns an empty options set so the notification is delivered silently and your app handles the payload directly.

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification,
                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    if Appoxee.shared()?.showNotificationsOnForeground ?? false {
        if #available(iOS 14.0, *) {
            completionHandler([.banner, .list, .sound, .badge])
        } else {
            completionHandler([.alert, .sound, .badge])
        }
    } else {
        completionHandler([])
    }
}

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {

    if ([[Appoxee shared] showNotificationsOnForeground]) {
        if (@available(iOS 14.0, *)) {
            completionHandler(UNNotificationPresentationOptionBanner | UNNotificationPresentationOptionList | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
        } else {
            completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
        }
    } else {
        completionHandler(UNNotificationPresentationOptionNone);
    }
}

Warning

.alert (Swift) and UNNotificationPresentationOptionAlert (Objective-C) are deprecated since iOS 14; use .list and .banner for iOS 14+ targets. The #available / @available branch keeps the example compatible with the SDK's iOS 12 minimum deployment target.

This method only controls how a notification is shown in the foreground. When the user taps the notification, iOS calls userNotificationCenter(_:didReceive:withCompletionHandler:) instead. Your app must forward this call to the SDK, otherwise landing pages, deep links and click tracking do not work. For code examples, see Forward Notification Taps in Manual Integration in Swift or Manual Integration in Objective-C. With the Basic Automated Setup, this applies only if your app sets itself as the delegate.

Note

• Foreground notifications require explicit handling; otherwise, they won't appear by default in iOS.

• Ensure notifications respect user preferences, such as disabling sounds or alerts when requested.

• Test notification behavior in different app states (foreground, background, and terminated).