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

The Connect SDK supports the following push notification features. Each is authored by your marketing team in Message composer:

• Thumbnail images in the collapsed notification, useful for branding such as a logo.
• Expandable content shown when the user expands the notification — either additional text or a full image.
• Actionable notifications, with a built-in action that fires when the user taps — open the app, call a number, or open a URL.

The notification icon that appears in the status bar and next to the notification is configured in your app code, not in Message composer. See Step 4 for requirements.

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. Connect administrator — uploads your FCM credentials to your Mobile app integration in Connect

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

Step 1: Set up Firebase Cloud Messaging

Set up Firebase in your project following the Firebase guide. All steps are required, with the following considerations:

• If your project uses applicationIdSuffix for debug builds, register the debug package name as a separate app in your Firebase project before downloading google-services.json.

• Google Analytics is optional and unrelated to push notifications.
• We recommend using the Firebase Android BoM to control library versioning.

Once you have completed the Firebase guide, generate a service account key: in the Firebase console, go to Settings > Service accounts and click Generate new private key. Connect uses this file to authenticate with FCM on your behalf when sending push notifications. For more information, see Initialize the SDK in non-Google environments.

Step 2: Share FCM credentials with your Connect administrator

Share the service account key 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

Replace the connect dependency with connect-push-fcm and add firebase-messaging. connect-push-fcm extends the core SDK with push notification support; firebase-messaging enables FCM message delivery.

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

    implementation(platform("com.google.firebase:firebase-bom:34.14.0"))
    implementation("com.google.firebase:firebase-messaging")
}

Sync the project after making this change.

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

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 (24×24 dp) with no android:tint attribute — 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

Notification permission

On Android 13 and above, ConnectPushConfig automatically requests the POST_NOTIFICATIONS runtime permission when the app launches. Use the onPermissionResult callback to react to the user's response — for example, to update UI or show a rationale if the user denies. No manual registerForActivityResult call is needed.

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

Before testing, confirm that your Connect administrator has completed Step 5 — push notifications will not be delivered and no FCM token will be received until the service account key is uploaded to Connect.

Testing push notifications requires a physical device with Google Play Services and an active internet connection — the Android emulator does not support FCM delivery.

1. Connect a physical Android device and run the app.
2. Grant notification permission when prompted.
3. Verify that a push token is received. Open the contact's activity feed in Connect and confirm a push token registration signal appears.
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 at sign-in — 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.
• Identify users at registration — send an account registered signal after sign-up to create or match a contact from their first session.
• Enable push notifications in an Android app (Huawei) — add HMS support to reach users on Huawei devices.
• Prepare for production — configure your Firebase and Connect setup for production, enable ProGuard rules, and get your app ready to ship.