---
title: Support Flutter Add-to-app - Flutter
description: Integrate Flutter screens into a native iOS or Android app that runs the Contentsquare SDK, using Flutter add-to-app.
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/add-to-app/
  md: https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/add-to-app/index.md
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

If your native iOS or Android app already runs the Contentsquare SDK ([iOS](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/), [Android](https://docs.contentsquare.com/en/csq-sdk-android/experience-analytics/)) and embeds Flutter screens with [add-to-app ↗](https://docs.flutter.dev/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

Flutter 3.35 or later is required. Earlier versions have a `FlutterEngine` [issue ↗](https://github.com/flutter/flutter/pull/172871) that was fixed in 3.35.

## Initialize the Flutter module

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**

```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());
}
```

> **Always call init**
>
> Always call `CSQ().init()`, whether or not the native SDK has been started or opted in. If you skip it, the Dart side isn't initialized. Initialization will never start tracking if not already started, but rather prepares the Dart side to connect to the native SDK once it is ready.

## Set up iOS

On iOS, the order of the following calls is mandatory. Missing a step is silent.

### 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**

```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

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**

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

> **Warning**
>
> If the plugin isn't registered on the engine yet, `register` does nothing and reports no error. Register the plugins on the engine first.

## Set up Android

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**

```kotlin
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)
  }
}
```

## 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()` 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.


```json
{"@context":"https://schema.org","@type":"TechArticle","headline":"Support Flutter Add-to-app","description":"Integrate Flutter screens into a native iOS or Android app that runs the Contentsquare SDK, using Flutter add-to-app.","url":"https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/add-to-app/","inLanguage":"en","dateModified":"2026-11-13T17:10:37+01:00","publisher":{"@type":"Organization","name":"Contentsquare","url":"https://www.contentsquare.com/"},"isPartOf":{"@type":"WebSite","@id":"https://docs.contentsquare.com/#website","name":"Contentsquare Technical Documentation","url":"https://docs.contentsquare.com/"}}
```