# Push Notifications
Configure and implement push notifications for iOS and Android platforms.
# Push Notifications
> How to configure your application to receive and respond to notifications.
## Platform Setup
Before you can send and receive push notifications, you need to configure your app for the platform(s) you're targeting. Follow the platform-specific setup instructions below.
### iOS
#### Enable Push Notifications Capability
1. Open your project in Xcode.
2. Click on your project in the Project Navigator.
3. Select your main app target and then click the **Signing & Capabilities** tab.
4. If you do not see Push Notifications enabled, click **+ Capability** and add **Push Notifications**.
*Adding the Push Notifications capability in Xcode*
#### Enable Background Modes
1. Select your main app target and then click the **Signing & Capabilities** tab.
2. Click **+ Capability** and add **Background Modes**.
*Adding the Background Modes capability in Xcode*
3. In the **Background Modes** section, select the **Remote notifications** checkbox.
*Enabling Remote notifications in Background Modes*
#### Notification Service Extension
To take advantage of notification attachments, such as images,
animated gifs, and video, you will need to create a notification service extension .
Follow the steps in the [iOS Notification Service Extension Guide](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/).
### Android
Configure Firebase Cloud Messaging (FCM) or Huawei Mobile Services (HMS) to enable push notifications on Android.
#### FCM Setup
Follow the [Android FCM setup instructions](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/#fcm-setup).
#### HMS Setup
1. Follow [Huawei's documentation](https://developer.huawei.com/consumer/en/doc/development/HMSCore-Guides/android-integrating-sdk-0000001050040084) to set up the HMS SDK.
> **Note:** Airship requires HMS Core Push SDK 6.3.0.304 or newer.
2. Add `airshipHmsEnabled=true` to the app's gradle.properties.
#### Notification Configuration
Configure the notification icon and accent color in your `takeOff` config:
```typescript
await Airship.takeOff({
production: {
appKey: "",
appSecret: ""
},
development: {
appKey: "",
appSecret: ""
},
inProduction: true,
site: "us",
android: {
notificationConfig: {
icon: "ic_notification",
accentColor: "#00ff00"
}
}
})
```
See the [Capacitor Plugin Setup guide](https://www.airship.com/docs/developer/sdk-integration/capacitor/installation/getting-started/) for complete `takeOff` configuration options.
## Enable User Notifications
The Airship SDK distinguishes between *user notifications* (visible to users) and *silent push notifications* (background data delivery). User notifications require explicit permission from the user.
By default, user notifications are disabled. Enable them when you want to show visible notifications to users.
### Basic Enablement
The simplest way to enable user notifications is with `setUserNotificationsEnabled()`:
```typescript
await Airship.push.setUserNotificationsEnabled(true)
```
This will prompt the user for permission if not already granted. However, it does not provide feedback on whether the user accepted or denied the permission.
> **Note:** For apps that target Android 13 (API 33) and above, enabling user notifications will display a runtime permission prompt.
>
> 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.
### Async Enablement with Fallback
For more control over the permission flow, use `enableUserNotifications()` which returns the permission result and supports a fallback option:
```typescript
// Enable with system settings fallback
const granted = await Airship.push.enableUserNotifications({
fallback: "systemSettings"
})
if (granted) {
console.log('Notifications enabled')
} else {
console.log('Notifications denied')
}
```
The `systemSettings` fallback option will prompt the user to open system settings if permission is denied on iOS or denied silently on Android. This gives users a second chance to enable notifications if they initially declined.
### Checking Notification Status
To check if user notifications are currently enabled:
```typescript
const enabled = await Airship.push.isUserNotificationsEnabled()
```
For more detailed status information, use `getNotificationStatus()`:
```typescript
const status = await Airship.push.getNotificationStatus()
console.log('Are notifications allowed:', status.areNotificationsAllowed)
console.log('Is opted in:', status.isOptedIn)
```
To monitor notification status changes in real-time:
```typescript
const handle = await Airship.push.onNotificationStatusChanged(event => {
console.log('Notification status changed:', event.status)
console.log('Is opted in:', event.status.isOptedIn)
})
```
### Getting the Push Token
To get the platform-specific push token (APNs token on iOS, FCM token on Android):
```typescript
const token = await Airship.push.getPushToken()
// Or listen for token updates
const handle = await Airship.push.onPushTokenReceived(event => {
console.log('Push token:', event.pushToken)
})
```
If push notifications aren't working as expected, see [Troubleshooting Push Notifications](https://www.airship.com/docs/developer/sdk-integration/capacitor/troubleshooting/push-notifications/) to check notification status and fix common issues.
# Notification Events
> How to handle push notification events, respond to user interactions, and manage active notifications.
The Airship SDK provides event listeners for when a push is received or a notification is interacted with.
## Push Received
Listen for when a push notification is received:
```typescript
const handle = await Airship.push.onPushReceived(event => {
console.log('Push received:', event.pushPayload)
})
```
This event fires when a push notification arrives, regardless of whether the app is in the foreground or background.
## Notification Response
Listen for when a user interacts with a notification:
```typescript
const handle = await Airship.push.onNotificationResponse(event => {
console.log('Notification tapped:', event)
console.log('Action ID:', event.actionId)
if (event.actionId === 'custom_action') {
// Handle custom action
}
})
```
This event fires when a user taps on a notification or a notification action button.
## Managing Active Notifications
You can retrieve and clear notifications that are currently displayed in the notification center.
### Get Active Notifications
Retrieve the list of currently displayed notifications:
```typescript
const notifications = await Airship.push.getActiveNotifications()
console.log('Active notifications:', notifications)
```
> **Note:** On Android, this list only includes notifications sent through Airship.
### Clear Notifications
Clear all notifications for the app:
```typescript
await Airship.push.clearNotifications()
```
Clear a specific notification by identifier:
```typescript
await Airship.push.clearNotification(identifier)
```
> **Note:** On Android, you can use this method to clear notifications outside of Airship. The identifier is in the format `:`.
# Customize Notifications
> How to customize push notification presentation, badges, quiet time, and foreground display behavior.
## 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.
```typescript
await Airship.push.iOS.setNotificationOptions([
"alert",
"badge",
"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.
```typescript
await Airship.push.iOS.setNotificationOptions([
"alert",
"badge",
"sound",
"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.
```typescript
await Airship.push.iOS.setForegroundPresentationOptions([
"banner",
"list",
"sound"
])
```
### Badges
The badge on iOS presents a counter on top of the application icon. You can control this directly through Airship.
```typescript
// 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.
```typescript
// Set quiet time hours
await Airship.push.iOS.setQuietTime({
startHour: 22,
startMinute: 0,
endHour: 7,
endMinute: 0
})
// Enable quiet time
await Airship.push.iOS.setQuietTimeEnabled(true)
```
> **Note:** Quiet time is only supported on iOS.
## Android Foreground Notifications
By default, push notifications received while the app is in the foreground on Android are displayed to the user. You can control this behavior globally:
```typescript
// Disable foreground notifications
await Airship.push.android.setForegroundNotificationsEnabled(false)
// Enable foreground notifications
await Airship.push.android.setForegroundNotificationsEnabled(true)
```
## 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.
For Android, all push messages are delivered in the background, but default Airship will treat messages without an `alert` as silent. For iOS, set the `content_available` property to `true` in the [iOS override object](https://www.airship.com/docs/developer/rest-api/ua/schemas/platform-overrides/#iosoverrideobject).
> **Note:** Pushes sent with the `content_available` property (iOS) or without an `alert` (Android) do not have guaranteed delivery. Factors affecting delivery include battery life, whether the device is connected to WiFi, and the number of silent pushes sent within a recent time period. These metrics are determined solely by iOS/Android and APNs/FCM. 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.