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

Language: JavaScript, with TypeScript definitions

Availability: Pro, Premium, and Ultimate

Scope: Test setup — building, running on a connected device or emulator, and verifying push delivery.

Sample app: See our GitHub repository for a reference implementation to compare your configuration against.

Prerequisites

• A Firebase project with your Android app registered. If you don't have one, create it at console.firebase.google.com.
• The Connect Cordova plugin integrated in your project, with a Connect app key from a Mobile app integration created after April 2026 — earlier integrations don't support push. See Integrate the Connect SDK into a Cordova app to install the plugin first.

Overview

1. Get your Firebase service account key.
2. Share your Firebase credentials with your Connect administrator.
3. Add google-services.json to your Cordova project root.
4. Add a notification icon.
5. Request notification permission from your users.

Step 1: Generate a Firebase service account key

1. In the Firebase console, open your project.
2. Go to Project settings > Service accounts.
3. Click Generate new private key and confirm. Firebase downloads a .json file.

Connect uses this file to authenticate with FCM on your behalf when sending push notifications.

Step 2: Share Firebase credentials with your Connect administrator

Share the following with your Connect administrator so they can enable push on your Mobile app integration.

📘

Note

Your Connect administrator needs to upload these credentials to your Mobile app integration before push notifications will be delivered. Steps 3–5 can be completed while you wait. See Connect mobile apps in the Connect user guide.

Step 3: Add google-services.json

1. In the Firebase console, go to Project settings > General.
2. Under Your apps, select your Android app.
3. Download google-services.json and place it at your Cordova project root — alongside ConnectConfig.json, not inside platforms/android/.

The plugin's Android after_prepare hook copies it into platforms/android/app/ on every npx cordova prepare android. The package name inside the file must match your config.xml widget id.

🚧

Warning

The plugin applies the com.google.gms.google-services Gradle plugin unconditionally. If google-services.json is missing at prepare time, the Android build hard-fails with File google-services.json is missing. The Google Services Plugin cannot function without it. — there's no way to build for Android without it, even to test unrelated functionality.

You don't need to add the Firebase Messaging dependency yourself — build-extras.gradle declares firebase-messaging (via the Firebase BoM) automatically alongside the connect-push-fcm artifact.

Step 4: Add a notification icon

Android requires a small monochrome icon for the notification drawer. The system applies a color tint at display time; design it as a white icon on a transparent background.

1. In Android Studio, right-click platforms/android/app/src/main/res (or your Android resource source if you keep one outside platforms/) and select New > Image Asset.
2. Set Icon type to Notification Icons, name it, and import your source image.
3. Click Next > Finish.

The plugin resolves the icon in this order at enable() time:

1. AndroidNotificationIconResName in ConnectConfig.json, if set and the drawable exists.
2. The plugin's own bundled ic_notification drawable — the correct default. Launcher icons are adaptive WebP and are not valid notification icons; using one crashes at delivery with a fatal IllegalArgumentException.
3. ic_launcher (legacy fallback — may not exist in mipmap-only projects).

If every lookup fails, the underlying SDK's own default is used, and the plugin logs an error telling you to add ic_notification.xml or set AndroidNotificationIconResName.

{
  "Connect": {
    "AppKey": "YOUR_PUSH_ENABLED_APP_KEY",
    "PostMessageUrl": "YOUR_COLLECTOR_URL",
    "AndroidNotificationIconResName": "ic_notification"
  }
}

Step 5: Request notification permission

On Android 13 (API 33) and later, your app must request notification permission at runtime. Call push.requestPermission() at an appropriate moment in your UX — for example, after an onboarding screen that explains the value of notifications.

const result = await AcousticConnect.push.requestPermission();

if (result.granted) {
  console.log('Notification permission granted');
} else {
  console.log('Notification permission denied:', result.error);
}

push.requestPermission() presents the system permission dialog on Android 13+ when the state is undetermined. On Android 12 and earlier, notifications are granted by default and the method resolves immediately with { granted: true }.

You can also check the current permission state without prompting:

const granted = await AcousticConnect.push.getPermissionState();
// true = granted, false = denied, null = not yet determined

Testing

Enabling SDK debug logging

Before testing, set "useRelease": false in ConnectConfig.json (the default) so Logcat shows verbose SDK output — filter by tag ConnectPlugin, Tealeaf, EOCore, or Connect. If you ever need to report an issue to support, attach your Logcat output.

Testing push delivery

Testing push notifications requires a physical device or an emulator with Google Play Services — FCM does not work on AOSP emulators.

1. Connect your device via USB and select it as the run target.
2. Build and run: npx cordova run android.
3. Grant notification permission when prompted. A new mobile contact is created in Connect and your device becomes eligible to receive pushes.
4. Coordinate with your marketing team to send a test push to your device, or do it yourself — see Test your push notification setup.
5. Verify the notification appears, and push signals appear in the contact's activity feed in Connect.

Message structure

Your marketing team creates message content in Message composer in Connect.

• Notification icon — always taken from the development project (see Step 4), not from Message composer.
• Title and body — authored per message.
• Thumbnail image — shown in the collapsed notification.
• Expandable content — additional text or image shown when the user expands the notification.
• Actionable notifications — tap behavior.

Troubleshooting

Push notifications not received

• Confirm google-services.json is present at your Cordova project root and matches your Firebase project and package name.
• Confirm the file was copied into platforms/android/app/ — check the after_prepare console output for [acoustic-connect] google-services.json copied to .... If you instead see a warning that it was not found, it means the plugin build proceeded with a missing file (this can only happen if the Google Services Gradle plugin somehow didn't hard-fail first — worth reporting as unexpected if you hit it).
• On API 33+, confirm the user granted notification permission — call push.getPermissionState() to check.

Push signals not appearing in Connect

• Confirm AppKey and PostMessageUrl in ConnectConfig.json match your Mobile app integration in Connect.
• Confirm your Connect administrator uploaded your Firebase service account key — push signals aren't sent without it.

Notification icon not showing correctly

• Confirm AndroidNotificationIconResName matches the drawable resource name exactly (no extension, no folder path).
• Confirm the icon is a white monochrome design on a transparent background.

File google-services.json is missing

The Google Services Gradle plugin hard-fails without it. Download it from Firebase Console and place it at your Cordova project root, then re-run npx cordova prepare android.

No matching client found for package name '...'

The package name in google-services.json doesn't match your Cordova project's widget id. This happens if you downloaded the file for a different Firebase Android app (for example, a separate dev/prod environment) or changed config.xml's widget id after registering with Firebase. In the Firebase console, confirm the Android app under Project settings has the same package name as the id attribute on your config.xml's <widget> element, then re-download google-services.json.

Next step: Identify app users

Push setup is now complete. To make the most of push notifications, identify the people receiving them — see Identify users at sign-in.