# Push Notifications for the React Native Module

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

Before setting up push notifications in your app, you need to configure push services in the Airship dashboard. See [iOS Channel Configuration](https://www.airship.com/docs/guides/getting-started/developers/configure-channels/#ios-channel-configuration) for APNs setup and [Android Channel Configuration](https://www.airship.com/docs/guides/getting-started/developers/configure-channels/#android-channel-configuration) for FCM setup.

## Platform Setup

Before you can send and receive push notifications, you need to configure your app for the platform(s) you're targeting.

### iOS


#### Standard React Native



#### 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 React Native Module](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 React Native Module](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 React Native Module](https://www.airship.com/docs/images/ios-background-mode-remote-notifications_hu_7e38b08288fcd7b2.webp)

#### Notification Service Extension

<p>To take advantage of notification attachments, such as images,
animated gifs, and video, you will need to create a <a href="https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications" target="_blank">notification service extension<span class="external-link-icon">&thinsp;<i class="ph ph-arrow-square-out"></i></span></a>.</p> Follow the steps in the [iOS Notification Service Extension Guide](https://www.airship.com/docs/developer/sdk-integration/apple/push-notifications/notification-service-extension/).



#### Expo



The Airship Expo plugin automatically configures iOS capabilities (Push Notifications and Background Modes) and the Notification Service Extension. No manual Xcode configuration is required.




### Android

Configure Firebase Cloud Messaging (FCM) to enable push notifications on Android.

#### FCM Setup


#### Standard React Native



1. Download the Android Firebase configuration file `google-services.json` from the application's Firebase console into the root directory at `android/app/google-services.json`.

   If your react-native application does not have an associated app in the Firebase console, follow the [FCM setup instructions](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/#fcm-setup) to set one up.



#### Expo



Expo automatically handles the `google-services.json` file through its build process. See the [Expo documentation](https://docs.expo.dev/push-notifications/fcm-credentials/) for details on configuring FCM credentials.




#### 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:

```ts
Airship.takeOff({
    default: {
        appKey: "REPLACE_WITH_YOUR_APP_KEY",
        appSecret: "REPLACE_WITH_YOUR_APP_SECRET"
    },
    site: "us",
    android: {
        notificationConfig: {
            icon: "ic_notification",
            accentColor: "#00ff00"
        }
    }
});
```


See the [React Native Setup guide](https://www.airship.com/docs/developer/sdk-integration/react-native/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: PromptPermissionFallback.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
Airship.addListener(EventType.PushNotificationStatusChangedStatus, (event) => {
  console.log('Notification status changed:', event.status);
  console.log('Is opted in:', event.status.isOptedIn);
});
```


### Getting the Registration Token

To get the platform-specific push token (APNs token on iOS, FCM token on Android):

```typescript
const token = await Airship.push.getRegistrationToken();
```


For more advanced event handling and token updates, see [Handling Notification Events](https://www.airship.com/docs/developer/sdk-integration/react-native/push-notifications/handling-notification-events/).

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