Skip to Content
Mobile SDKsFlutter

Flutter SDK

engage_flutter exposes an idiomatic Dart facade while delegating persistence, synchronization, push, in-app evaluation, Message Center, and feature flags to the native Engage SDKs. Native content is embedded through Flutter Platform Views.

Requirements

  • Flutter 3.41 or newer;
  • Android API 24 or newer, Java 17, and core library desugaring;
  • iOS 15 or newer;
  • Flutter Swift Package Manager support enabled for iOS.

Install

flutter pub add engage_flutter

Android host setup

Add JitPack to android/build.gradle.kts:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io") {
            content { includeGroup("com.github.mathias8dev.engage-android") }
        }
    }
}

If the project uses RepositoriesMode.FAIL_ON_PROJECT_REPOS, put that declaration in dependencyResolutionManagement.repositories in android/settings.gradle.kts instead.

Enable desugaring:

android {
    defaultConfig { minSdk = 24 }
    compileOptions { isCoreLibraryDesugaringEnabled = true }
}
 
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

Start

await Engage.start(
  config: const EngageConfig(
    appKey: String.fromEnvironment('ENGAGE_APP_KEY'),
    logLevel: EngageLogLevel.verbose,
  ),
);

Use --dart-define=ENGAGE_APP_KEY=eng_app_… or your build configuration system. The first validated start is persisted by the Android bridge so cold FCM processing can initialize native Engage before a Flutter engine attaches. A later Dart start must match it.

Runtime model

  • Replaying state such as installation ID, privacy, push readiness, unread count, and placement state is exposed as multicast streams.
  • Push events are non-replaying broadcast events.
  • Feature flag getters are Future<T> because they cross the platform channel, although native evaluation uses a local snapshot.
  • Embedded in-app and Message Center UI is rendered natively. Flutter owns layout constraints and navigation chrome.
  • The Flutter Preference Center is a host-composed widget; the native ready-made presentation remains available through the bridge.
  • Native versions are pinned by the plugin; Flutter and native releases are versioned independently.

Preference Center

Available on the current develop branch and intended for the next Flutter release.

Compose the ready-made content inside the route and application chrome owned by the host:

Navigator.of(context).push(
  MaterialPageRoute(
    builder: (_) => Scaffold(
      appBar: AppBar(title: const Text('Communication preferences')),
      body: const SafeArea(
        top: false,
        child: EngagePreferenceCenter(centerKey: 'marketing'),
      ),
    ),
  ),
);

EngagePreferenceCenter creates no route, Scaffold, app bar, or navigation behavior. It inherits the surrounding Material 3 theme and locale. This lets the screen remain consistent with the application’s own navigation architecture.

To present the native Android Activity or iOS controller instead:

await Engage.preferenceCenter.display(
  key: 'marketing',
  theme: EngageMaterialTheme.of(context),
);

Use Engage.preferenceCenter.center(key) for a headless implementation. Snapshot semantics and mutation APIs are detailed in Preferences, feature flags, and privacy.

Logs

Use EngageLogLevel.verbose while integrating. Dart uses logger name Engage; Android uses Logcat tag Engage; iOS uses subsystem io.engage.sdk. Sensitive values are redacted.

Endpoint migration

Available on the current develop branch and intended for the next Flutter release.

EngageConfig(
  appKey: const String.fromEnvironment('ENGAGE_APP_KEY'),
  endpoint: const String.fromEnvironment('ENGAGE_ENDPOINT'),
  legacyEndpoints: [const String.fromEnvironment('PREVIOUS_ENGAGE_ENDPOINT')],
)

Use this only for a one-time endpoint migration, not for ordinary releases.

AndroidiOS