# Push Notifications for the Apple SDK

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

Before setting up push notifications in your app, you need to configure APNs (Apple Push Notification service) in the Airship dashboard. See [iOS Channel Configuration](https://www.airship.com/docs/guides/getting-started/developers/configure-channels/#ios-channel-configuration) for instructions on uploading your APNs certificate or token.

## Enable Capabilities

Before enabling push notifications, you need to configure your app's capabilities in Xcode.

### 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**.

    ![Push Notifications for the Apple SDK](https://www.airship.com/docs/images/ios-enable-push-notifications-capabilities_hu_2e1789fffb02612b.webp)

### Enable Background Modes

1. Select your main app target and then click the **Signing & Capabilities** tab.
2. Click **+ Capability** and add **Background Modes**.

    ![Push Notifications for the Apple SDK](https://www.airship.com/docs/images/ios-enable-background-mode-capabilities_hu_f135d9fec0ba0d06.webp)

3. In the **Background Modes** section, select the **Remote notifications** checkbox.

    ![Push Notifications for the Apple SDK](https://www.airship.com/docs/images/ios-background-mode-remote-notifications_hu_7e38b08288fcd7b2.webp)

## Add Rich Media Support

To support rich media attachments (images, animated GIFs, video) in push notifications, you need to create a Notification Service Extension. See [Notification Service Extension](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/) for setup instructions.

## 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 to set the `userPushNotificationsEnabled` property:


#### Swift


```swift
Airship.push.userPushNotificationsEnabled = true
```



#### Objective-C


```objc
UAirship.push.userPushNotificationsEnabled = YES;
```




### Checking Authorization State

To check whether the user granted permission, use the async method which returns the system authorization state:


#### Swift


```swift
let authorized = await Airship.push.enableUserPushNotifications()
if authorized {
    // User granted permission
} else {
    // User denied permission
}
```



#### Objective-C


> **Note:** This async method is not available in Objective-C. Use the basic `userPushNotificationsEnabled` property instead.




> **Note:** The return value represents the **system authorization state** (whether the user granted permission), not the state of `userPushNotificationsEnabled`, which will always be set to `true` after calling this method.


### Handling Denied Permissions

If the user has already denied notification permissions, you can provide a fallback action to guide them to system settings or show a custom message:


#### Swift


```swift
// Navigate to system settings if permission is denied
let authorized = await Airship.push.enableUserPushNotifications(
    fallback: .systemSettings
)

// Or provide a custom callback
let authorized = await Airship.push.enableUserPushNotifications(
    fallback: .callback {
        // Show custom UI explaining why notifications are important
        // and guide user to system settings
    }
)

// Or no fallback
let authorized = await Airship.push.enableUserPushNotifications(
    fallback: .none
)
```



#### Objective-C


> **Note:** This async method is not available in Objective-C. Use the basic `userPushNotificationsEnabled` property instead.




The `PromptPermissionFallback` options are:

- `.none` - No fallback action
- `.systemSettings` - Automatically navigate to system settings if permission is denied
- `.callback` - Execute a custom callback to handle the denied state

> **Tip:** To increase the likelihood that users will accept notification permissions, avoid prompting immediately on app launch. Instead, wait for a more appropriate moment, such as after the user completes an action or views relevant content.


## Configure Notification Options

Before enabling user notifications, you can configure which notification types your app will request permission for.

### Standard Notification Options

By default, the Airship SDK requests permission for alerts, badges, and sounds. You can customize these options:


#### Swift


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



#### Objective-C


```objc
UAirship.push.notificationOptions = (UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert);
```




### Provisional Authorization

Provisional authorization allows you to send notifications without initially prompting the user. Notifications are delivered quietly to the Notification Center until the user explicitly chooses to keep them.


#### Swift


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



#### Objective-C


```objc
UAirship.push.notificationOptions = (UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert | UNAuthorizationOptionProvisional);
```




> **Note:** With provisional authorization, you can programmatically enable user notifications without showing a permission prompt. This is still required for any visible notification delivery.


## Foreground Presentation Options

When your app is in the foreground, iOS silences notifications by default. Configure how notifications are displayed when the app is active:


#### Swift


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



#### Objective-C


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




## Handle Notification Events

The Airship SDK provides callbacks for when notifications are received or interacted with. These callbacks are optional—the SDK will handle notifications automatically if you don't set them.


#### Swift


```swift
// Handle when user taps a notification
Airship.push.onReceivedNotificationResponse = { response in
    // Handle notification response
}

// Handle notification received while app is in foreground
Airship.push.onReceivedForegroundNotification = { userInfo in
    // Handle foreground notification
}

// Handle background content-available notification
Airship.push.onReceivedBackgroundNotification = { userInfo in
    // Handle background notification
    return .noData
}

// Customize presentation options per notification
Airship.push.onExtendPresentationOptions = { options, notification in
    // Return presentation options for this specific notification
    return [.badge, .list, .banner, .sound]
}
```



#### Objective-C


```objc
// Handle when user taps a notification
UAirship.push.onReceivedNotificationResponse = ^(UNNotificationResponse *response) {
    // Handle notification response
};

// Handle notification received while app is in foreground
UAirship.push.onReceivedForegroundNotification = ^(NSDictionary *userInfo) {
    // Handle foreground notification
};

// Handle background content-available notification
UAirship.push.onReceivedBackgroundNotification = ^UIBackgroundFetchResult(NSDictionary *userInfo) {
    // Handle background notification
    return UIBackgroundFetchResultNoData;
};

// Customize presentation options per notification
UAirship.push.onExtendPresentationOptions = ^UNNotificationPresentationOptions(UNNotificationPresentationOptions options, UNNotification *notification) {
    // Return presentation options for this specific notification
    return UNNotificationPresentationOptionList | UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound;
};
```




## Silent Notifications

Silent notifications are push messages that don't display a notification to the user. They're typically used to wake your app in the background to perform tasks or fetch content.

To send a silent notification, 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).

> **Important:** Thoroughly test your implementation to confirm that silent notifications don't generate any visible device notifications.


> **Note:** Silent notifications (`content_available`) don't have guaranteed delivery. Factors affecting delivery include battery life, WiFi connectivity, and the number of silent pushes sent recently. These metrics are determined solely by iOS and APNs.
> 
> Use silent notifications to supplement your app's regular behavior rather than for critical functionality. For example, use them to pre-fetch data ahead of time to reduce load times when the user launches the app.


## Next Steps

- [Notification Service Extension](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/) - Add rich media support to push notifications
- [Interactive Notifications](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/interactive-notifications/) - Add action buttons to notifications
- [Badge Management](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/badge-management/) - Set, reset, or enable auto-badge functionality
- [Quiet Time](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/quiet-time/) - Suppress notifications during specific hours
- [App Clips](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/app-clips/) - Configure push notifications for App Clips

If push notifications aren't working as expected, see [Troubleshooting Push Notifications](https://www.airship.com/docs/developer/sdk-integration/apple/troubleshooting/push-notifications/) to check notification status and fix common issues.