Mobile troubleshooting

Android artifacts cannot be found

Typical error:

Could not find com.github.mathias8dev.engage-android:engage-android-core:…

Add https://jitpack.io to the consuming application’s repositories. Installing engage_flutter from pub.dev does not add repositories to the host Gradle build. With FAIL_ON_PROJECT_REPOS, declare JitPack in android/settings.gradle.kts.

EngageFlutterPlugin cannot be found

Ensure the installed package contains the expected native plugin, then clear stale generated registration state:

flutter clean
flutter pub get

Confirm that pubspec.lock resolves the intended published package or local path. A partially edited local plugin may expose a Dart package while failing to compile its Kotlin class.

No installation appears

1. Enable verbose/debug Engage logs.
2. Confirm the app key begins with eng_app_ and belongs to the expected environment/app.
3. Confirm the endpoint is reachable from the device.
4. Observe SDK startup state and installation ID.
5. Check privacy and runtime feature state.
6. Do not substitute a server access key for the app key.

Push permission is granted but no notification arrives

Check all layers:

• system notification permission;
• Engage.push subscription is opted in;
• tokenRegistered is true;
• FCM/APNs credentials are valid in the targeted Engage app;
• the campaign targets the correct environment and app;
• audience and subscription list eligibility;
• provider diagnostics, TTL, priority, and device restrictions;
• Android notification channel is enabled by the user.

Android shows a generic bell icon

Configure smallIcon / smallIconResource with an Android monochrome status-bar drawable. Launcher icons are adaptive full-color assets and are not valid substitutes for notification small icons.

The same Android push appears more than once

Remove any host FirebaseMessagingService path that posts Engage messages independently. The Engage FCM module already owns message processing and deduplication. Verify the campaign was not sent multiple times and inspect provider delivery IDs.

iOS push works through Firebase but not Engage

Engage iOS delivery is direct to APNs. Upload APNs credentials to Engage, enable the app capabilities, start Engage, and forward APNs registration callbacks. APNs credentials stored only in Firebase are not used by Engage.

In-app content does not appear

Confirm the experience is active and published, targets the app, has an eligible audience, valid schedule, matching trigger, available allocation, and remaining frequency. Check overlay pause/delegate decisions and conflict priority. For embedded content, match the placement key exactly.

Message Center entry remains unread

The SDK marks an entry read when the detail snapshot is actually visible. Opening a list row without successfully presenting detail does not mark it read. Check the DETAIL published surface and unavailable callback.

Logs and support bundle

Collect app key prefix, environment/app name, installation ID, SDK version, app version, platform version, timestamps, campaign/request ID, and redacted Engage logs. Never include provider credentials, access keys, installation credentials, tokens, or binding codes.