Error Analysis

You must include the Contentsquare SDK first using the same integration method and understand how the SDK works.

To enable Error Analysis in your application and ensure optimal stability, make sure to always use the last SDK version.

Tracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the Flutter Track screens sections.

If you are in the process of implementing the SDK for the 1st time, or if you choose to take this update as an opportunity to review your privacy-related implementation, ensure that you follow the Flutter Privacy section and use the Opt-in API to get the user consent, otherwise no data will be collected.

You do not need to do anything to start the Error Analysis SDK, it will start itself with Contentsquare SDK.

When the SDK starts, you should see a log like this one:

// success case
CSLIB ℹ️ Info: Contentsquare Error Analysis [SDKVersionNumber] starting in app : [your.app.packageName]

// fail case
// << No public fail log

API Errors automatically collects failed network requests.

By default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the Contentsquare.setURLMaskingPatterns SDK API.

Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable:

• :user_id becomes CS_ANONYMIZED_USER_ID
• :address becomes CS_ANONYMIZED_ADDRESS

import 'package:contentsquare/contentsquare.dart';

Contentsquare.setURLMaskingPatterns(patterns: [
  'https://www.contentsquare.com/users/:user_id/address/:address',
]);

If in-app features are enabled, a info log should appear with the details of the event (see Flutter Debugging and Logging section):

CSLIB ℹ️ Info: API Error - GET 401 https://api.client.com

Our SDK automatically starts upon application launch and seamlessly captures failed network requests.

Once started, our SDK fetches its config from our servers. It will start collecting data from network events if the API Errors setting is enabled in the config (this is handled by the Contentsquare team).

The SDK monitors only the API Errors with response code 400 and above, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches.

For each network error, a new event will be sent in Analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent:

• Analytics requests
• Session Replay requests

API Errors troubleshooting details feature enhances your ability to collect additional information about API errors, facilitating faster troubleshooting.

With this feature, you can view three types of additional API error details in the Event Stream of Session Replay:

• The HTTP headers of the request and the response.
• The body (the data sent by the request or received in the response).
• The query parameters of the request endpoint (of the URL of the information you request for).

See API Troubleshooting Details ↗ for more details.

Only network calls in error (response code 400 and above) will be collected.
Here is the exhaustive list of data collected:

• URL (without query strings)
• HTTP method
• Response code
• Timestamp of the request
• Timestamp of the response
• HTTP headers of the request
• HTTP headers of the response
• HTTP body of the request
• HTTP body of the response
• Query parameters

Contentsquare Error Analysis is not compatible with Firebase Performance Monitoring auto-collection. Only one of the two will log events, and usually, the events will be automatically logged by the Contentsquare Error Analysis. To log events to Firebase Performance Monitoring, we suggest logging it manually ↗.

Contentsquare Error Analysis is compatible with Firebase Performance auto-collection, but the HTTP body from the response won’t be collected by the Error Analysis SDK.

Contentsquare Error Analysis may not be compatible with other network auto-collection tools.

Use ContentsquareHttpOverrides if you need to override the global HttpOverrides.

import 'dart:io';
import 'package:contentsquare/contentsquare.dart' show ContentsquareHttpOverrides;

class YourCustomHttpOverrides extends HttpOverrides {
  @override
  HttpClient createHttpClient(SecurityContext? context) {
    return super.createHttpClient(context);
  }
}

void main() {
  HttpOverrides.global = ContentsquareHttpOverrides(
    httpOverrides: YourCustomHttpOverrides(),
  );
}

You can collect unhandled errors from the framework by using the FlutterError.onError ↗ callback. However, errors that occur outside of Flutter’s callbacks, such as asynchronous errors, will not be captured. To handle these, consider implementing the PlatformDispatcher.onError ↗ or runZonedGuarded ↗ callbacks.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  FlutterError.onError = (FlutterErrorDetails details) {
    // Collects Flutter errors
    Contentsquare().collectFlutterError(details: details);
  };
  WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) {
    // Collects all unhandled errors from the root isolate, including platform-level errors
    Contentsquare().collectError(error: exception, stackTrace: stackTrace);
    return false;
  };
  runApp(MyApp());
}

void main() async {
  runZonedGuarded(() {
    FlutterError.onError = (FlutterErrorDetails details) {
      // Collects Flutter errors
      Contentsquare().collectFlutterError(details: details);
    };
    runApp(MyApp());
  }, (error, stack) {
    // Collects all unhandled errors in the zone
    Contentsquare().collectError(error: error, stackTrace: stack);
  });
}

Contentsquare automatically presents ↗ the Flutter errors. You can disable it by using the optional presentErrorDetails parameter in collectFlutterError API.

Contentsquare().collectFlutterError(details: details, presentErrorDetails: false);

Integrating Crashlytics as an additional error reporting solution is straightforward: include the corresponding instruction within each callback.

void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (FlutterErrorDetails details) {
      Contentsquare().collectFlutterError(details: details, presentErrorDetails: false);
      FirebaseCrashlytics.instance.recordFlutterError(details);
    };
    WidgetsBinding.instance.platformDispatcher.onError = (exception, stackTrace) {
      Contentsquare().collectError(error: exception, stackTrace: stackTrace);
      FirebaseCrashlytics.instance.recordError(exception, stackTrace);
      return false;
    };
    runApp(MyApp());
  }

1. Enable the in-app features.
2. Run your application. You should see a log printed in the console:

┌───────────────────────────────────────────────────────────────────────────────
│ ℹ️ INFO ℹ️ (CSLIB)
├───────────────────────────────────────────────────────────────────────────────
│ Errors Reporter module has started.
└───────────────────────────────────────────────────────────────────────────────

With in-app features enabled, any errors occurring in your application should generate a log in the console:

┌───────────────────────────────────────────────────────────────────────────────
│ ℹ️ INFO ℹ️ (CSLIB)
├───────────────────────────────────────────────────────────────────────────────
│ Error was collected.
│ Exception: type 'String' is not a subtype of type 'int' in type cast
└───────────────────────────────────────────────────────────────────────────────

To be able to read errors from an application built with Flutter obfuscation and/or de-symbolisation, you will need to upload the debug files to Contentsquare.

1. Enable the contentsquare_cli plugin

2. Run the upload command

The upload command must be executed immediately after the Flutter build.

• Android: 3.10.6
• iOS: 3.13.0

Error Reporter is started automatically and begins to collect the reported errors when your application is launched

Once started, our SDK fetches its configuration from our servers. It will start reporting errors if the Error Reporter setting is enabled (this is handled by the Contentsquare team).

You have to implement an error handler strategy and collect the received errors. See Flutter errors for examples

When an error occurs, a report is created and stored locally in the device. The report is sent to our servers as soon as possible and then removed from the local storage.

For each error, a new event will be sent to analytics and Session Replay data when the network conditions allow for the server to be reached.

Crashes from the native parts of your application can be captured with additional setup.

See 📚 iOS Crash Reporter.

See 📚 Android Crash Reporter.

Errors occurring in web pages loaded in WebViews can be collected if Webview tracking is setup in your app.

See 📚 Webview Tracking implementation.

Once WebView tracking is implemented, errors collection can be set up.

See 📚 Errors (in WebView)