This guide walks you through enabling push notifications in your Android app using Firebase Cloud Messaging (FCM) and the Acoustic Connect SDK.

Languages: Kotlin and Java

Availability: Pro, Premium, and Ultimate

Scope: This guide covers setting up push notifications for development and testing. For production configuration, see Prepare the Connect library for production use on Android devices.

Prerequisites

• Connect SDK 11.0.11 or later, integrated into your app. See the integration guide for your architecture: View-based or Jetpack Compose. If you are upgrading from SDK 10.x, see the update guide.
• Your project meets the Firebase prerequisites for Android.

Overview

1. You — set up Firebase Cloud Messaging in your project
2. You — share your FCM credentials with your Connect administrator
3. You — update your Gradle configuration
4. You — add push configuration to the SDK initialization code
5. You — request notification permission from your users (Android 13 and later)
6. Connect administrator — uploads your FCM credentials to your Mobile app integration in Connect

Steps 3–5 can be completed while waiting for your Connect administrator to complete Step 6. Push notifications will not be delivered until Step 6 is done.

Step 1: Set up Firebase Cloud Messaging

Set up Firebase in your project following the Add Firebase to your Android project guide. All steps are required, including downloading the google-services.json config file and placing it in your app's app/ directory.

Step 2: Share FCM credentials with your Connect administrator

Generate a service account key in the Firebase console and share it with your Connect administrator. They'll upload it to your Mobile app integration in Connect. Your app key will stay the same.

Step 3: Update your Gradle configuration

Remove the connect entry from your dependencies and replace it with connect-push-fcm. This artifact includes push support and pulls in the core connect library and Firebase Messaging transitively — you do not need to declare them separately.

plugins {
    id 'com.android.application' version '8.4.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.22' apply false
    id 'com.google.gms.google-services' version '4.4.1' apply false
}

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'com.google.gms.google-services'
}

dependencies {
    implementation "io.github.go-acoustic:connect-push-fcm:11.0.11"
}

For a working example, see app/build.gradle.kts in the sample app for your architecture:

• View-based: app/build.gradle.kts
• Jetpack Compose: app/build.gradle.kts

📘

Note

Only devices with Google Play Services will receive push notifications. We recommend checking for a compatible Google Play Services APK at runtime — in both onCreate() and onResume() of your main activity. See Check whether Google Play services is installed in the Android documentation.

Step 4: Add push configuration to the SDK

Add a ConnectPushConfig to your existing SDK initialization call.

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Connect.init(this)
        Connect.enable(
            appKey = "YOUR_APP_KEY",
            postMessageUrl = "YOUR_COLLECTOR_URL",
            pushConfig = ConnectPushConfig(
                application = this,
                iconRes = R.drawable.ic_notification,
                onTokenReady = { token -> },
                onFailure = { exception -> },
                onPermissionResult = { isGranted -> }
            )
        )
    }
}

ConnectWrapper(
    navController = navController,
    appKey = "YOUR_APP_KEY",
    postMessageURL = "YOUR_COLLECTOR_URL",
    pushConfig = ConnectPushConfig(
        application = application,
        iconRes = R.drawable.ic_notification,
        onTokenReady = { token -> },
        onFailure = { exception -> },
        onPermissionResult = { isGranted -> }
    )
) {
    // Your app content
}

For a working example, see the relevant MainActivity.kt in the sample app for your architecture:

• View-based: MainActivity.kt
• Jetpack Compose: MainActivity.kt

Notification icon

Replace R.drawable.ic_notification with a drawable resource from your app. This icon appears on the left side of the notification and in the status bar. It must be entirely white on a transparent background (24x24 dp) — if a colored icon is used, Android will display a white square instead. You can generate a compliant icon using Android Asset Studio.

For a reference implementation, see ic_notification.xml in the sample app for your architecture:

• View-based: ic_notification.xml
• Jetpack Compose: ic_notification.xml

Step 5: Request notification permission (Android 13 and later)

On Android 13 (API level 33) and later, push notifications require the POST_NOTIFICATIONS runtime permission. Add the following to your main activity:

class MainActivity : ComponentActivity() {

    private val requestNotificationPermission =
        registerForActivityResult(ActivityResultContracts.RequestPermission()) { granted ->
            // Handle the result if needed
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            requestNotificationPermission.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}

The permission declaration is already included in the SDK's manifest — you do not need to add it to your app's AndroidManifest.xml.

To check the current permission state without prompting the user:

val isPushEnabled = Connect.push.isPushAccepted(context)

Try the sample app

Two reference implementations are available, one for each architecture:

• Acoustic Connect Mobile Push Sample App for Android (XML) — View-based app demonstrating SDK initialization with push configuration, notification permission handling, and identity signaling.
• Acoustic Connect Mobile Push Sample App for Android (Compose) — Jetpack Compose app with the same feature coverage using ConnectWrapper.

Troubleshooting

Testing

Testing push notifications requires a physical device — the Android emulator does not support FCM delivery.

1. Connect a physical Android device to your computer via USB (or Wi-Fi) and run the app from Android Studio, the same way you would run it on an emulator. The device must have Google Play Services and an active internet connection.
2. Grant notification permission when prompted.
3. Verify that a push token is received. You can log it via the onTokenReady callback in ConnectPushConfig.
4. Coordinate with your marketing team to send a test push to your device.
5. Verify the notification appears, images load, and push signals appear in the contact's activity feed in Connect.

Next steps

Push setup is now complete. To make the most of push notifications, try this:

• Identify users — by default, app visitors are anonymous and cannot be matched to people your marketing team already knows. Identity signals let you connect them to known contacts in your Connect audience.
• Prepare for production — configure separate Firebase projects for dev and production, enable ProGuard rules, and get your app ready to ship.