Getting Started with Push Notifications

How to configure your application to receive and respond to notifications.

Enabling user notifications

Enabling userPushNotificationsEnabled will prompt the user for permission to send notifications. To increase the likelihood that the user will accept, you should avoid prompting the user for permission immediately, and instead wait for a more appropriate time in the app.

The Airship SDK makes a distinction between user notifications, which can be seen by the user, and other forms of push that allow you to send data to your app silently, or in the background. Enabling or disabling user notifications is a preference often best left up to the user, so by default, user notifications are disabled.

Enable user notifications

UAirship.shared().pushManager.userNotificationsEnabled = true

UAirship.shared().getPushManager().setUserNotificationsEnabled(true);

UAirship.push.userPushNotificationsEnabled = true

UAirship.push.userPushNotificationsEnabled = YES;

await Airship.push.setUserNotificationsEnabled(true);

Airship.push.setUserNotificationsEnabled(true);

Airship.push.setUserNotificationsEnabled(true);

await Airship.push.setUserNotificationsEnabled(true)

using AirshipDotNet;

Airship.Instance.UserNotificationsEnabled = true

using UrbanAirship.NETStandard;

Airship.Instance.UserNotificationsEnabled = true

Airship.push.userNotificationsEnabled = true

UAirship.Shared.UserNotificationsEnabled = true;

Note

For apps that target Android 13 (API 33) and above, enabling user notifications will display a runtime permission prompt to allow notifications to be sent.

To increase the likelihood that the user will accept, you should avoid prompting the user for permission immediately on app startup, and instead wait for a more appropriate time to prompt for notification permission.

Notification callbacks

The Airship SDK provides several callbacks for when a push is received or a notification is interacted with. Apps can use these callbacks to do custom push processing. Registering for a callback is optional, the SDK will automatically launch the application without the need to set a callback.

Listening for notifications

airship.pushManager.addPushListener { message: PushMessage, notificationPosted: Boolean ->
    // Called when a message is received
}

airship.pushManager.notificationListener = object : NotificationListener {
    override fun onNotificationPosted(notificationInfo: NotificationInfo) {
        // Called when a notification is posted
    }

    override fun onNotificationOpened(notificationInfo: NotificationInfo): Boolean {
        // Called when a notification is tapped.
        // Return false here to allow Airship to auto launch the launcher activity
        return false
    }

    override fun onNotificationForegroundAction(
        notificationInfo: NotificationInfo,
        actionButtonInfo: NotificationActionButtonInfo
    ): Boolean {
        // Called when a notification action button is tapped.
        // Return false here to allow Airship to auto launch the launcher activity
        return false
    }

    override fun onNotificationBackgroundAction(
        notificationInfo: NotificationInfo,
        actionButtonInfo: NotificationActionButtonInfo
    ) {
        // Called when a background notification action button is tapped.
    }

    override fun onNotificationDismissed(notificationInfo: NotificationInfo) {
        // Called when a notification is dismissed
    }
}

airship.getPushManager().addPushListener((message, notificationPosted) -> {
    // Called when any push is received
});

airship.getPushManager().setNotificationListener(new NotificationListener() {
    @Override
    public void onNotificationPosted(@NonNull NotificationInfo notificationInfo) {
        // Called when a notification is posted
    }

    @Override
    public boolean onNotificationOpened(@NonNull NotificationInfo notificationInfo) {
        // Called when a notification is tapped.
        // Return false here to allow Airship to auto launch the launcher activity
        return false;
    }

    @Override
    public boolean onNotificationForegroundAction(@NonNull NotificationInfo notificationInfo, @NonNull NotificationActionButtonInfo actionButtonInfo) {
        // Called when a notification action button is tapped.
        // Return false here to allow Airship to auto launch the launcher activity
        return false;
    }

    @Override
    public void onNotificationBackgroundAction(@NonNull NotificationInfo notificationInfo, @NonNull NotificationActionButtonInfo actionButtonInfo) {
        // Called when a background notification action button is tapped.
    }

    @Override
    public void onNotificationDismissed(@NonNull NotificationInfo notificationInfo) {
        // Called when a notification is dismissed
    }
});

class CustomPushHandler: NSObject, PushNotificationDelegate {

    public func receivedBackgroundNotification(_ userInfo: [AnyHashable : Any], completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        // Background content-available notification
        completionHandler(.noData)
    }

    public func receivedForegroundNotification(_ userInfo: [AnyHashable : Any], completionHandler: @escaping () -> Void) {
        // Foreground notification
        completionHandler()
    }

    public func receivedNotificationResponse(_ notificationResponse: UNNotificationResponse, completionHandler: @escaping () -> Void) {
        // Notification response
        completionHandler()
    }

    public func extend(_ options: UNNotificationPresentationOptions, notification: UNNotification) -> UNNotificationPresentationOptions {
        return [.alert, .sound]
    }
}

Airship.push.pushNotificationDelegate = customPushHandler

@implementation CustomPushHandler

-(void)receivedBackgroundNotification:(UNNotificationContent *)notificationContent completionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    // Background content-available notification
    completionHandler(UIBackgroundFetchResultNoData);
}

-(void)receivedForegroundNotification:(UNNotificationContent *)notificationContent completionHandler:(void (^)(void))completionHandler {
    // Foreground notification
    completionHandler();
}

-(void)receivedNotificationResponse:(UNNotificationResponse *)notificationResponse completionHandler:(void (^)(void))completionHandler {
    // Notification response
    completionHandler();
}

- (UNNotificationPresentationOptions)extendPresentationOptions:(UNNotificationPresentationOptions)options notification:(UNNotification *)notification {
    // Foreground presentation options
    return UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound;
}
@end

Set the PushNotificationDelegate

UAirship.push.pushNotificationDelegate = customPushHandler;

Airship.addListener(EventType.PushReceived, (event) => {
    // handle push received event
});

Airship.addListener(EventType.NotificationResponse, (response) => {
    // handle response
});

// Push received. Will not be called on Android when the app is terminated. Use a background
// message handler instead.
Airship.push.onPushReceived.listen((event) => debugPrint('Push Received $event'));

Airship.push.onNotificationResponse.listen((event) => debugPrint('Notification Response $event'));

Android background push handler

Future<void> backgroundMessageHandler(PushReceivedEvent event) async {
  // Handle the message
  debugPrint("Received background message: $event");
}

void main() {
  Airship.push.android.setBackgroundPushReceivedHandler(backgroundMessageHandler);
  runApp(MyApp());
}

// Called when a push is received.
// This will be delivered only in the foreground on Android
Airship.push.onPushReceived((event) => {
    // handle event
})

// Notification responses
Airship.push.onNotificationResponse((event) => {
    // handle event
})

// Called when a push is received.
await Airship.push.onPushReceived(event => {
// handle event
})

// Notification responses
await Airship.push.onNotificationResponse(event => {
// handle event
})

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Only called in the foreground on Android
Airship.addEventListener(Airship.Airship.eventPushReceived, function(e) {
    // handle event
})

Airship.addEventListener(Airship.Airship.eventNotificationResponseReceived, function(e) {
    // handle event
})

UAirship.Shared.OnPushReceived += (PushMessage message) => {
  // Handle message
};

UAirship.Shared.OnPushOpened += (PushMessage message) => {
  // Handle message
};

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.

Important

We recommend that you thoroughly test your implementation to confirm that silent notifications do not generate any device notifications.

To send a silent notification on iOS, set the content_available property to true in the iOS override object. For Android, all push messages are delivered in the background, but default Airship will treat messages without an alert as silent.

Note

Pushes sent with the content_available property do not have guaranteed delivery. Factors affecting delivery include battery life, whether the device is connected to WiFi, and the number of content_available pushes sent within a recent time period. These metrics are determined solely by iOS and APNs. Therefore, this feature is best used for supplementing the regular behavior of the app rather than providing critical functionality. For instance, an app could use a silent push to pre-fetch new data ahead of time in order to reduce load times when the app is later launched by the user.

Common iOS Settings

Notification Options

By default, the Airship SDK will request Alert, Badge, and Sound notification options for remote notifications. This can be configured by setting notification options before enabling user notifications.

Update notification options

// Not supported

// Not supported

Airship.push.notificationOptions = [.alert, .badge, .sound]

UAirship.push.notificationOptions = (UANotificationOptionAlert | UANotificationOptionBadge | UANotificationOptionSound);

  await Airship.push.iOS.setNotificationOptions([
    iOS.NotificationOption.Alert,
    iOS.NotificationOption.Badge,
    iOS.NotificationOption.Sound,
  ]);

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

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

await Airship.push.iOS.setNotificationOptions([
        "alert",
        "badge",
        "sound",
    ])

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

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. Because this form of authorization requires no initial user prompt, it is acceptable to programmatically enable user notifications, which is still required for any visible notification delivery.

Requesting provisional authorization

// Not supported

// Not supported

Airship.push.notificationOptions = [.alert, .badge, .sound, .provisional]

UAirship.push.notificationOptions = (UANotificationOptionAlert | UANotificationOptionBadge | UANotificationOptionSound | UANotificationOptionProvisional);

  await Airship.push.iOS.setNotificationOptions([
    iOS.NotificationOption.Alert,
    iOS.NotificationOption.Badge,
    iOS.NotificationOption.Sound,
    iOS.NotificationOption.Provisional,
  ]);

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

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

await Airship.push.iOS.setNotificationOptions([
     "alert", 
     "badge",
     "sound",
     "provisional"
  ])

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

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.

Setting default presentation options

// Not supported

// Not supported

Airship.push.defaultPresentationOptions = [.alert, .badge, .sound]

UAirship.push.defaultPresentationOptions = (UNNotificationPresentationOptionAlert |
                                            UNNotificationPresentationOptionBadge |
                                            UNNotificationPresentationOptionSound);

  await Airship.push.iOS.setForegroundPresentationOptions([
    iOS.ForegroundPresentationOption.List,
    iOS.ForegroundPresentationOption.Badge,
    iOS.ForegroundPresentationOption.Sound,
  ]);

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

  Airship.push.ios.setForegroundPresentationOptions([
    "banner",
    "list",
    "sound"
  ]);

  await Airship.push.ios.setForegroundPresentationOptions([
    "banner",
    "list",
    "sound"
  ])

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

Badges

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

Setting the badge value

// Not supported

// Not supported

Airship.push.badgeNumber = 20

UAirship.push.badgeNumber = 20

await Airship.push.iOS.setBadgeNumber(20);

Airship.push.iOS.setBadge(20);

Airship.push.ios.setBadgeNumber(20)

await Airship.push.ios.setBadgeNumber(20)

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

Badge can be reset by setting the badge to 0 or calling reset.

Reset the badge

// Not supported

// Not supported

Airship.push.resetBadge()

[UAirship.push resetBadge];

await Airship.push.iOS.setBadgeNumber(0);

Airship.push.iOS.resetBadge();

Airship.push.ios.resetBadge()

await Airship.push.iOS.setBadgeNumber(0)

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

Additionally, Airship support an auto-badge feature. This allows incrementing the badge from a push instead of setting the exact value for the badge. When using auto-badge, make sure to only modify the badge value through Airship methods to ensure the value keeps in sync.

Enabling auto-badge

// Not supported

// Not supported

Airship.push.autobadgeEnabled = true

UAirship.push.autobadgeEnabled = YES;

await Airship.push.iOS.setAutobadgeEnabled(true);

Airship.push.iOS.setAutoBadgeEnabled(true);

Airship.push.ios.setAutobadgeEnabled(true);

await Airship.push.ios.setAutobadgeEnabled(true)

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

Quiet Time

Setting default presentation options

// Not supported

// Not supported

// Set the quiet time from 7:30pm - 7:30am
Airship.push.setQuietTimeStartHour(19, startMinute: 30, endHour: 7, endMinute: 30)

// Enable quiet time
Airship.push.quietTimeEnabled = true

// Set the quiet time from 7:30pm - 7:30am
[UAirship.push setQuietTimeStartHour:19 startMinute:30 endHour:7 endMinute:30];

// Enable quiet time
UAirship.push.quietTimeEnabled = YES;

// Not supported

// Not supported

Airship.push.ios.setQuietTime({
    startHour: 19, 
    startMinute: 30, 
    endHour: 7, 
    endMinute: 30
})

// Enable quiet time
Airship.push.ios.setQuietTimeEnabled(true)

await Airship.push.ios.setQuietTime({
    startHour: 19,
    startMinute: 30,
    endHour: 7,
    endMinute: 30
})

// Enable quiet time
await Airship.push.ios.setQuietTimeEnabled(true)

// Not supported in Airship.NET library. Use native binding methods instead.

// Not supported in Airship .NETStandard library. Use native binding methods instead.

// Not supported

// Not supported

Feedback

Was this page helpful?