For the complete documentation index, see llms.txt.

Support Flutter Add-to-app

Last updated View as MarkdownSet up with AI

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.

Flutter 3.35 or later is required. Earlier versions have a FlutterEngine issue ↗ that was fixed in 3.35.

Call 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.

main.dart
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());
}

On 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 support

Call enableFlutterModuleSupport once, at startup, before any engine runs GeneratedPluginRegistrant.register(with:). Call CSQ.optIn() after CSQ.start() to get user consent and start tracking.

AppDelegate.swift
import UIKit
import Flutter
import contentsquare
import ContentsquareSDK
@UIApplicationMain
class 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 controller

Register 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.

HomeViewController.swift
import UIKit
import Flutter
import contentsquare
import 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.

On 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.

MyApplication.kt
import android.app.Application
import com.contentsquare.CSQ
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.embedding.engine.FlutterEngineCache
import 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)
}
}
  • 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() and CSQ.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.