Push Notifications

Enabling User Notifications

The Airship module makes a distinction between "user notifications", which can be seen by the user, and invisible notifications that carry only data for the app to process. 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
UrbanAirship.setUserNotificationsEnabled(true)

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 the file is added to your application's target in the same way you added AirshipConfig.plist in the Getting Started guide.

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 notifiation 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>

 

Listening for Events

notificationResponse
UrbanAirship.addListener("notificationResponse", (response) => {
  console.log('Notification response: ', JSON.stringify(response.notification));
  console.log('Notification response isForeground: ', response.isForeground);

  // will only be set for notification action buttons
  console.log('Notification response actionId: ', response.actionId);
});
pushReceived
UrbanAirship.addListener("pushReceived", (notification) => {
  console.log('Received push: ', JSON.stringify(notification));
});
deepLink
UrbanAirship.addListener("deepLink", (event) => {
  console.log('Deep link: ', event.deepLink);
});
register
UrbanAirship.addListener("register", (event) => {
  console.log('Channel registration updated: ', event.channelId);
  console.log('Registration token: ', event.registrationToken);
});
notificationOptInStatus
UrbanAirship.addListener("notificationOptInStatus", (event) => {
  console.log('User notifications opted in: ', event.optIn);

  // iOS only
  console.log('User notifications options: ', JSON.stringify(event.notificationOptions));
});
inboxUpdated
UrbanAirship.addListener("inboxUpdated", (event) => {
  console.log('Message center updated. Unread count: ' + event.messageUnreadCount + 'Total message count: ' + event.messageCount);
});

Available events:

notificationResponse
Event fired when a user responds to a notification from either tapping the main notification or one of the action buttons.
pushReceived
Event fired when a push is received.
deepLink
Event fired when a new deep link is available. The app should navigate to the proper page when the event is received.
register
Event fired when channel registration updates.
notificationOptInStatus
Event fired when a user notification opt-in status changes. This event only fires in the foreground and for iOS devices includes the alert, sound, and badge opted-in options.
inboxUpdated
Event fired when the inbox is updated. The event includes the total message count and the total unread message count.