> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Push Notifications

> Set up and customize push notifications with the Userpilot Android SDK

Configure Firebase and deep linking to receive, display, and handle Userpilot push notifications on Android.

The Userpilot SDK supports push notifications to help you deliver targeted messages and enhance user engagement.

## Prerequisites

Configure your Android push settings in the [Userpilot Settings Studio](https://run.userpilot.io/settings/mobile) before setting up push notifications in your app.

To obtain the required keys and configuration details, refer to the [Android Push Notification Guide](../android-push-notification-setup-guide).

## Setup

This guide assumes this is the first time you're adding push notification code to your project using Google services (Firebase Cloud Messaging). If your project is already configured for push, proceed to Step 2.

**Step 1. Add Firebase**

Follow the steps in the official Google documentation on [How to add Firebase to your project](https://firebase.google.com/docs/android/setup).

**Step 2. Request Notifications Permission**

Starting from Android 13 (API level 33), apps must explicitly request the `POST_NOTIFICATIONS` permission to display push notifications.

The Userpilot SDK **automatically** requests push notifications permission on its own.

**Step 3. Add the Userpilot Firebase Messaging Service**

Firebase connects to your app through a `<service>`. Add the following to your `AndroidManifest.xml`:

```xml theme={null}
<service
    android:name="com.userpilot.pushNotifications.UserpilotFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
```

If your project already has a child of `FirebaseMessagingService`, you can leave it as is and instead plug in `UserpilotFirebaseMessagingService` to your service class.

```kotlin theme={null}
import com.userpilot.pushNotifications.UserpilotFirebaseMessagingService
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class CustomFirebaseMessageService : FirebaseMessagingService() {
    override fun onMessageReceived(message: RemoteMessage) {
        if (UserpilotFirebaseMessagingService.handleMessage(baseContext, message)) {
           // handled as Userpilot message
           return
        }

        // not Userpilot message
        super.onMessageReceived(message)
        }

    override fun onNewToken(token: String) {
        // sets new token from the callback
        UserpilotFirebaseMessagingService.setToken(token)

        super.onNewToken(token)
    }
}
```

**Step 4. Deep Linking**

To ensure your app **opens automatically when a Userpilot push notification is clicked**, you need to configure an `intent-filter` in your app's \*\*entry \*\*`Activity` in `Manifest.xml` .

This configuration enables deep linking based on a custom scheme defined in your app.

**Define the Deep Link Scheme** In your `userpilot.xml` configuration file, you should have defined a value for `userpilot_push_notification` , check Step 5.

**Update Manifest** file to include the intent-filter as below. Make sure to set `host="sdk"` .

```xml theme={null}
<activity
    android:name=".features.main.MainActivity"
    android:exported="true"
    android:launchMode="singleTop">

    <!-- Default launcher intent filter -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Intent filter for push notification deep linking -->
    <intent-filter>
        <data android:scheme="userpilot_push_notification" android:host="sdk" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>
```

**Step 5. Handling Notification Intent**

Inside your entry point activity, pass the intent to the Userpilot SDK to handle it.

```kotlin theme={null}
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
  
    handleIntentUserpilotIntent(intent)
}


override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    if (handleIntentUserpilotIntent(intent)) return
}


 /** If not handled by Userpilot, then let app handle it. */
private fun handleIntentUserpilotIntent(intent: Intent): Boolean {
    return userpilot.onNewIntent(intent)
}
```

**Step 6. Customization**

The Userpilot SDK allows customization for how messages are delivered. These properties are set as `<resources>` values. To change them, create a file under `res/values` and set the desired values.

```xml theme={null}
<resources>
    <!-- Small icon displayed in the notification bar -->
    <drawable name="userpilot_notification_small_icon">@drawable/ic_notification</drawable>

    <!-- Accent color applied to notification UI elements -->
    <color name="userpilot_notification_color">#6765E8</color>

    <!-- Determines if notifications are visible on the lock screen (true = visible) -->
    <bool name="userpilot_notification_channel_lock_screen_visibility">true</bool>

    <!-- Enables notification lights for the channel -->
    <bool name="userpilot_notification_channel_enable_light">true</bool>

    <!-- Enables vibration for the notifications -->
    <bool name="userpilot_notification_channel_enable_vibration">true</bool>

    <!-- Unique ID for the notification channel -->
    <string name="userpilot_notification_channel_id">com.userpilot.general.channel</string>

    <!-- Human-readable name for the notification channel -->
    <string name="userpilot_notification_channel_name">General</string>

    <!-- Description shown to the user about this notification channel -->
    <string name="userpilot_notification_channel_description">Default channel used for app messages</string>

    <!-- Importance level of the notification channel (0 = NONE, 5 = MAX) -->
    <integer name="userpilot_notification_channel_importance">3</integer>

    <!-- Key used to identify Userpilot push notifications -->
    <string name="userpilot_push_notification">userpilot_push_notification</string>
</resources>
```

<Frame>
  [**For any questions or concerns please reach out to support@userpilot.com**](mailto:support@userpilot.com)
</Frame>