Support Flutter Add-to-app
If your native iOS or Android app already runs the Contentsquare SDK (iOS, Android) and embeds Flutter screens with add-to-app ↗, the CSQ Flutter SDK attaches to the native SDK. The native SDK keeps control of the app lifecycle, and each Flutter view connects to it through its own bridge.
Requirements
Section titled RequirementsFlutter 3.35 or later is required. Earlier versions have a FlutterEngine issue ↗ that was fixed in 3.35.
Initialize the Flutter module
Section titled Initialize the Flutter moduleCall CSQ().init() before you start the Flutter app. It reads the native SDK configuration, and starts the Dart side ONLY if the native SDK has already started.
import 'package:flutter/material.dart';import 'package:contentsquare/csq.dart';
Future<void> main() async { WidgetsFlutterBinding.ensureInitialized();
// Gets the native SDK's config; starts the Dart side if native was already started. await CSQ().init(); runApp(const MyApp());}Set up iOS
Section titled Set up iOSOn iOS, the order of the following calls is mandatory. Missing a step is silent.
Start the SDK and enable Flutter module support
Section titled Start the SDK and enable Flutter module supportCall enableFlutterModuleSupport once, at startup, before any engine runs GeneratedPluginRegistrant.register(with:). Call CSQ.optIn() after CSQ.start() to get user consent and start tracking.
import UIKitimport Flutterimport contentsquareimport ContentsquareSDK
@UIApplicationMainclass AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { CSQ.start() CSQ.optIn() // once the user has given consent CSQ.enableFlutterModuleSupport(enable: true) // before plugin registration
let engine = FlutterEngine(name: "main_engine") engine.run() GeneratedPluginRegistrant.register(with: engine) return true }}Register each Flutter view controller
Section titled Register each Flutter view controllerRegister every FlutterViewController before you present it. This applies whether the parent view controller pushes, presents, or embeds it, and when you create it inside makeUIViewController for SwiftUI.
import UIKitimport Flutterimport contentsquareimport ContentsquareSDK
class HomeViewController: UIViewController { var engine: FlutterEngine! // the engine created at startup
func showFlutter() { let vc = FlutterViewController(engine: engine, nibName: nil, bundle: nil) CSQ.register(flutterViewController: vc) // must precede presentation present(vc, animated: true) }}register finds ContentsquarePlugin on the engine and binds the external bridge to the view of that controller.
Set up Android
Section titled Set up AndroidOn Android, the only required setup is to start the SDK from the native side, and to call CSQ.optIn() after CSQ.start() to get user consent and start tracking. The bridge automatically attaches to the native SDK when the Flutter view is created.
import android.app.Applicationimport com.contentsquare.CSQimport io.flutter.embedding.engine.FlutterEngineimport io.flutter.embedding.engine.FlutterEngineCacheimport io.flutter.embedding.engine.dart.DartExecutor
class MyApplication : Application() { override fun onCreate() { super.onCreate() CSQ.start(context = this) CSQ.optIn() // once the user has given consent
val engine = FlutterEngine(this) engine.dartExecutor.executeDartEntrypoint(DartExecutor.DartEntrypoint.createDefault()) FlutterEngineCache.getInstance().put("main_engine", engine) }}Limitations
Section titled Limitations- Embedded Flutter isn't supported. Non-fullscreen Flutter and multiple Flutter views in one native screen can produce incorrect Session Replay, touch targeting, or screenview attribution. The supported scenario is a fullscreen Flutter view or activity.
- Transitions can cause frame drops. Switching the Session Replay context between native and Flutter takes microseconds, and can cause frame drops right after navigation, especially on Android.
- Privacy considerations: Use the native APIs (
CSQ.optIn()andCSQ.optOut()) to opt in after an opt-out, rather than the Flutter APIs. - SDK Start: Ensure that the SDK is always started by the native and not the Flutter module.