Customize Notifications

Configure notification options, foreground presentation, badges, and custom categories.

iOS 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.

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

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.

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

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.

Global Foreground Presentation Options

Set default foreground presentation options for all notifications:

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

Per-Notification Foreground Presentation Options

For more control, you can override presentation options on a per-notification basis using a callback:

Airship.push.iOS.setForegroundPresentationOptionsCallback(async (pushPayload) => {
  // Check the push payload and return custom options
  if (pushPayload.extras?.highPriority) {
    // Show high priority notifications with all options
    return [
      iOS.ForegroundPresentationOption.List,
      iOS.ForegroundPresentationOption.Banner,
      iOS.ForegroundPresentationOption.Sound,
      iOS.ForegroundPresentationOption.Badge
    ];
  }
  
  // Return null to use the default options
  return null;
});

The callback receives the full push payload and should return quickly to avoid delaying notification delivery. Returning null uses the default options set with setForegroundPresentationOptions().

Badges

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.setBadgeNumber(20);

// Reset badge
await Airship.push.iOS.setBadgeNumber(0);

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

Important

When using auto-badge, only modify the badge value through Airship methods to ensure the value stays in sync.

Quiet Time

Quiet time allows you to suppress notifications during specific hours. Notifications are still received but won’t be displayed to the user during the quiet time window.

Note

Quiet time is only supported on iOS.

Android Notification Configuration

You can configure Android-specific notification behaviors and settings.

Foreground Display Control

By default, push notifications received while the app is in the foreground on Android are displayed to the user. You can control this behavior on a per-notification basis using a predicate:

Airship.push.android.setForegroundDisplayPredicate(async (pushPayload) => {
  // Check the push payload and return true to display, false to suppress
  if (pushPayload.extras?.silent) {
    return false; // Don't display notifications marked as silent
  }
  
  // Display all other notifications
  return true;
});

The predicate receives the full push payload and should return quickly to avoid delaying notification delivery. Return true to display the notification or false to suppress it.

Adding Custom Notification Categories

The Airship module supports adding custom notification categories on iOS, and custom notification action button groups on Android, by way of a specially named plist and XML file, respectively. Once these files are added to your iOS and Android projects, the module will load this file at runtime and automatically register your custom categories with the Airship API.

iOS Setup

Add a new plist file to your app’s Xcode project, named UACustomNotificationCategories.plist, and make sure to add the file to your application’s target.

The structure of the plist file follows the format used by the core Airship SDK for its default categories. As a starting point, see the example below. Note that key and string values prefixed with “ua_” are reserved by the Airship SDK.

UACustomNotificationCategories.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>yes_no_background</key>
    <array>
        <dict>
            <key>authenticationRequired</key>
            <true/>
            <key>foreground</key>
            <false/>
            <key>identifier</key>
            <string>yes</string>
            <key>title</key>
            <string>Yes</string>
            <key>title_resource</key>
            <string>notification_button_yes</string>
        </dict>
        <dict>
            <key>authenticationRequired</key>
            <true/>
            <key>foreground</key>
            <false/>
            <key>identifier</key>
            <string>no</string>
            <key>title</key>
            <string>No</string>
            <key>title_resource</key>
            <string>notification_button_no</string>
        </dict>
    </array>
    <key>yes_no_foreground</key>
    <array>
        <dict>
            <key>foreground</key>
            <true/>
            <key>identifier</key>
            <string>yes</string>
            <key>title</key>
            <string>Yes</string>
            <key>title_resource</key>
            <string>notification_button_yes</string>
        </dict>
        <dict>
            <key>authenticationRequired</key>
            <true/>
            <key>foreground</key>
            <false/>
            <key>identifier</key>
            <string>no</string>
            <key>title</key>
            <string>No</string>
            <key>title_resource</key>
            <string>notification_button_no</string>
        </dict>
    </array>
</dict>
</plist>

Android Setup

First, add a new xml file to your app’s main/res/xml directory, named ua_custom_notification_buttons.xml.

As with the iOS example above, the structure of this XML file follows the format used by the core Airship SDK for its default categories. And as before, entities and resource names with the “ua_” prefix are reserved by the Airship SDK. A similar example is given below. The icon and label resources shown are only examples; to create custom categories of your own, you should either use built-in Android resources or supply resources defined by your app.

ua_custom_notification_buttons.xml

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
    <UrbanAirshipActionButtonGroup id="yes_no_foreground">

        <UrbanAirshipActionButton
            foreground="true"
            id="yes"
            android:icon="@drawable/ic_notification_button_accept"
            android:label="@string/notification_button_yes"/>

        <UrbanAirshipActionButton
            foreground="false"
            id="no"
            android:icon="@drawable/ic_notification_button_decline"
            android:label="@string/notification_button_no"/>
    </UrbanAirshipActionButtonGroup>

    <UrbanAirshipActionButtonGroup id="yes_no_background">

        <UrbanAirshipActionButton
            foreground="false"
            id="yes"
            android:icon="@drawable/ic_notification_button_accept"
            android:label="@string/notification_button_yes"/>

        <UrbanAirshipActionButton
            foreground="false"
            id="no"
            android:icon="@drawable/ic_notification_button_decline"
            android:label="@string/notification_button_no"/>
    </UrbanAirshipActionButtonGroup>
</resources>

Adding Custom Notification Channels (Android)

The Airship module also supports adding custom notification channels on Android, by supplying a specially named XML file.

First, add a new xml file to your app’s main/res/xml directory, named ua_custom_notification_channels.xml.

The structure of this XML file follows the format used by the core Airship SDK for its default notification channels. A simple example is shown below. Note that entities and resource names with the “ua_” prefix are reserved by the Airship SDK. To create custom notification channels of your own, you should either use built-in Android resources or supply resources defined by your app.

ua_custom_notification_channels.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <NotificationChannel
        id="com.myapp.my_channel"
        name="@string/my_channel_name"
        description="@string/my_channel_description"
        importance="3" />
</resources>

Feedback

Was this page helpful?