---
title: Getting Started - Flutter (classic)
description: Load and validate the Contentsquare Flutter SDK installation in your app
lastUpdated: 07 April 2026
source_url:
  html: https://docs.contentsquare.com/en/flutter/
  md: https://docs.contentsquare.com/en/flutter/index.md
---

> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.

The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-flutter/experience-analytics/upgrade-from-cs-sdk/).

Welcome to the SDK implementation guide!

This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes.

## Install the SDK

With Flutter CLI:

```shell
flutter pub add contentsquare
```

This will add a line like this to your package's pubspec.yaml (and run an implicit `flutter pub get`):

**pubspec.yaml**

```yaml
dependencies:
  contentsquare: ^4.1.1
```

See [Compatibility](compatibility/) for more information.

## Start the SDK

1. Import the SDK

   ```dart
   import 'package:contentsquare/contentsquare.dart';
   ```

2. Add a call to start the SDK as early as possible, ideally in the `main()` function of your app.

   **main.dart**

   ```dart
   import 'package:contentsquare/contentsquare.dart';
   import 'package:flutter/material.dart';


   void main() async {
     await Contentsquare().start();
     runApp(const MyApp());
   }
   ```

   Alternatively you can start the SDK after user consent, for example on a button press:

   ```dart
   class UserConsentScreen extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           title: Text('User Consent'),
         ),
         body: Center(
           child: ElevatedButton(
             onPressed: () async {
               await Contentsquare().start();
             },
             child: Text('Agree with Terms and Conditions'),
           ),
         ),
       );
     }
   }
   ```

3. After calling `start()` you need to call `optIn()` to start tracking.

   ```dart
   class UserConsentScreen extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           title: Text('User Consent'),
         ),
         body: Center(
           child: ElevatedButton(
             onPressed: () async {
               await Contentsquare().start();
               await Contentsquare().optIn();
             },
             child: Text('Agree with Terms and Conditions'),
           ),
         ),
       );
     }
   }
   ```

## Validate SDK integration

Start your application, and check logs for this output:

```text
┌───────────────────────────────────────────────────────────────────────────────
│ 🔔 IMPORTANT 🔔 (CSLIB 4.1.1)
├───────────────────────────────────────────────────────────────────────────────
│ Contentsquare Flutter SDK 4.1.1 starting in app:
│ com.example.testapp
└───────────────────────────────────────────────────────────────────────────────
```

## Check the logs

Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Android Studio, Xcode, or on the Contentsquare platform.

To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled.

### Viewing local logs in IDE

* Android Studio

  To view SDK logs:

  1. Plug your Android phone into your computer (or use an emulator)
  2. Open Android Studio and start your app
  3. Open the `Logcat` view and select your phone or emulator
  4. Filter logs by `CSLIB`

  ![](https://docs.contentsquare.com/_astro/logs-android.DcmHNl7a_1VAzm1.webp)

* Xcode

  1. Unless you are using a simulator, ensure the device you are using is connected to your Mac or is on the same Wi-Fi network.
  2. Open the macOS Console app or Xcode.

  For the macOS Console app, make sure info messages are included at [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac).

  1. Filter logs by `CSLIB`.

  ![](https://docs.contentsquare.com/_astro/logs-ios.BkLL-Bb7_Z1Ovm29.webp)

### Enable In-app features

In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration.

To enable in-app features within your app, you have to **first make sure your app is launched in the background**. Then, follow the appropriate method described as follows.

#### On a device: scan the QR code

* Android

  In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.

  ![Scan the QR Code (Android)](https://docs.contentsquare.com/_astro/log-visualizer-access-qr.DnZz71r7_905Is.webp)

* iOS

  In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.

  ![Scan the QR Code (iOS)](https://docs.contentsquare.com/_astro/log-visualizer-access-qr.BMM1NnUy_1kl8Dd.webp)

#### On an emulator/simulator

* Android

  In Contentsquare, select the Mobile icon in the menu top bar then select your application ID, and "Copy this ADB command".

  ![](https://docs.contentsquare.com/_astro/log-visualizer-access-adb.BaJqetXO_zt9bH.webp)

* iOS

  In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.

  ![](https://docs.contentsquare.com/_astro/log-visualizer-access-custom-link.BcDGrin1_1QRynb.webp)

### Contentsquare Log Visualizer

Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log).

Prerequisite

To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings.

1. Start your app.
2. Select the Mobile icon in the menu top bar then select `Log Visualizer`.
3. Select the device to inspect.

At this stage, you should see an 'App start' or 'App show' event being logged.

* Android

  ![Log visualizer Android app start](https://docs.contentsquare.com/_astro/log-visualizer-app-start.CjWWxzSe_1CiJ7F.webp)

* iOS

  ![Log visualizer iOS app start](https://docs.contentsquare.com/_astro/log-visualizer-app-start.BMUhGlzy_ZUr40e.webp)

## Android permissions

When using the Contentsquare Flutter SDK on Android, the underlying native SDK requires specific permissions to function correctly.

These permissions are automatically included from the Contentsquare SDK into your app's `AndroidManifest.xml` at build time.

For the full list and detailed explanations, you can refer to the [Contentsquare Android SDK Required Permissions documentation](https://docs.contentsquare.com/en/android/security/#app-permissions).

Important

These permissions are mandatory and used exclusively for analytics purposes, in compliance with GDPR and CNIL (French regulation) requirements.

## Track your first screens

Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel.

### Sending screenview events

Screen tracking is achieved by sending a `screenview` each time a screen is displayed on the user's device.

Important

Sending at least one screen event is required to start tracking.

**home.dart**

```dart
import 'package:contentsquare/contentsquare.dart';
import 'package:flutter/material.dart';


class Home extends StatefulWidget {
  @override
  _HomeState createState() => _HomeState();
}
class _HomeState extends State<Home> {


  @override
  void initState() {
    super.initState();
    Contentsquare().send('Home');
  }


  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('Home'),
      ),
      body: const Center(
        child: Text('Welcome to Contentsquare!'),
      ),
    );
  }
}
```

### Implementation recommendations

For more detailed information on how to track screens, refer to the complete [screen tracking](https://docs.contentsquare.com/en/flutter/track-screens/) guide.

## Test your setup

Testing your SDK implementation is essential to make sure data is being accurately captured and reported.

To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform.

You can also use debugging tools such as Android Studio, Xcode, or Log Visualizer to monitor data transmission and ensure everything is running smoothly.

### Visualize events in Contentsquare

Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time.

By simulating user activity, you see incoming screenview and gesture events.

* Android

  ![Log visualizer Android activity](https://docs.contentsquare.com/_astro/log-visualizer-activity.x9zqNXUC_3mvS0.webp)

* iOS

  ![Log visualizer iOS activity](https://docs.contentsquare.com/_astro/log-visualizer-activity.DpcYyP1k_ZQkq96.webp)

### Visualize data in Contentsquare

Data availability

Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app.

#### In Journey Analysis

[Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.

![](https://docs.contentsquare.com/_astro/check-data-journay-analysis.CjaeeRjK_1Iime.webp)

See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161).

#### In Session Replay

[Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.

![](https://docs.contentsquare.com/_astro/check-data-session-replay.Cvuj2X01_HiOzM.webp)

See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561)

## Next Steps

While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior.

Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking.

Proceed with these how-to's to refine your implementation.

[Custom Variables ](https://docs.contentsquare.com/en/flutter/track-custom-variables/)Collect additional details about the screen or the user.

[Dynamic Variables ](https://docs.contentsquare.com/en/flutter/track-dynamic-variables/)Collect additional information about the session.

[Transactions tracking ](https://docs.contentsquare.com/en/flutter/track-transactions/)Associate user's session with their potential purchases and corresponding revenue.

[WebViews ](https://docs.contentsquare.com/en/flutter/track-webviews/)For native apps which embark web applications or pages.

[Session Replay ](https://docs.contentsquare.com/en/flutter/session-replay/)Collect data for Session Replay in compliance personal data masking.

[Error Analysis ](https://docs.contentsquare.com/en/flutter/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools.