clarity_flutter 1.0.0

The official Clarity Flutter SDK.

Official Clarity Flutter SDK

Overview

The Clarity Flutter SDK allows you to integrate Clarity analytics into your Flutter applications. This SDK is the latest addition to Clarity’s range of SDKs available for Native Android, iOS, React native, Cordova and Ionic. Clarity SDKs help you capture user interactions, screen views, and other important metrics to gain insights into user behavior and improve your business KPIs.

The SDK supports Flutter on both Android and iOS devices.

Contents

• Overview
• Features
• How Does Clarity Flutter SDK Work?
• Getting Started
• Integration Steps
  • Step 1: Add Dependency
  • Step 2: Import the Package
  • Step 3: Initialize and Wrap Your App
• Configuration Options
• Masking Widgets
  • ClarityMask
  • ClarityUnmask
• Troubleshooting
• Known Limitations

Features

• ✅ Session Recordings
• ✅ Heatmaps
• ✅ User interaction insights such as Rage taps, Dead taps, Taps, and Double taps.

Note: Smart Events, Funnels, and Components are not supported in the Clarity Flutter SDK at the moment.

How Does Clarity Flutter SDK Work?

Once the SDK is successfully integrated into the mobile application and is initialized, data is automatically captured and sent to Clarity’s servers. The SDK captures:

• User screens / visuals
• User interactions (taps, double taps, and touch motions)

Captured data is periodically uploaded .

Tip! You should see your current Live Session show up on the dashboard right away. The complete session data takes about 30 minutes up to 2 hours to show up on the dashboard.

Note: The current Flutter SDK only captures and uploads sessions when the device is connected to the internet.

Getting Started

To get started with Clarity, sign up and create a project. Follow the instructions on the Clarity SDK Getting Started page.

Integration Steps

Step 1: Add Dependency

Add the clarity_flutter dependency to your pubspec.yaml file.

dependencies:
  clarity_flutter: 1.0.0

Step 2: Import the Package

Import the clarity_flutter package in your main.dart file.

import 'package:clarity_flutter/clarity_flutter.dart';

Step 3: Initialize and Wrap Your App

Initialize the ClarityConfig object and wrap your app with the ClarityWidget widget.

import 'package:flutter/material.dart';
import 'package:clarity_flutter/clarity_flutter.dart';

void main() {
  final config = ClarityConfig(
    projectId: "your_project_id" // You can find it on the Settings page of Clarity dashboard. 
  );

  runApp(ClarityWidget(
    app: MyApp(),
    clarityConfig: config,
  ));
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('Clarity Flutter SDK Example'),
        ),
        body: Center(
          child: Text('Hello, Clarity!'),
        ),
      ),
    );
  }
}

Configuration Options

The ClarityConfig object has the following configuration options:

• projectId (String): The unique identifier for your Clarity project. You can find it on the Settings page of Clarity dashboard. This ID is essential for routing data to the correct Clarity project.
• userId (String, optional): The unique identifier for the user. Must be a base-36 string larger than 0 and smaller than 1z141z4. If not provided, a Clarity generated user ID will be used instead.
• logLevel (LogLevel, optional): The logging level for Clarity. Defaults to LogLevel.Info if not provided (in debug builds). Possible values are:
  • LogLevel.Verbose: Detailed debug information.
  • LogLevel.Debug: Debug information.
  • LogLevel.Info: Informational messages.
  • LogLevel.Warn: Warning messages.
  • LogLevel.Error: Error messages.
  • LogLevel.None: No logging.

  Tip! In non-debug (production) builds, loglevel is forced to None to eliminate any performance overhead.

Example:

final config = ClarityConfig(
  projectId: "your_project_id",
  userId: "your_user_id",
  logLevel: LogLevel.Info,
);

Masking Widgets

The Clarity Flutter SDK provides masking widgets to mask sensitive information in your app. These widgets are ClarityMask and ClarityUnmask.

Note: Clarity supports masking modes that are applied on the entire app. More on how to use them and what to expect here.

ClarityMask

Use ClarityMask to mask widgets containing sensitive information.

import 'package:flutter/material.dart';
import 'package:clarity_flutter/clarity_flutter.dart';

class MaskedWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ClarityMask(
      child: Text('Sensitive Information'),
    );
  }
}

ClarityUnmask

Use ClarityUnmask to unmask widgets within a masked area.

import 'package:flutter/material.dart';
import 'package:clarity_flutter/clarity_flutter.dart';

class UnmaskedWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ClarityUnmask(
      child: Text('Non-sensitive Information'),
    );
  }
}

Troubleshooting

If you can't see any data on the dashboard, follow these steps:

1. Set the Clarity log level to Verbose to check for initialization errors.
2. Filter the logs on [Clarity] to view Clarity-specific logs, to make sure clarity is running correctly.
3. Ensure your device is connected to the internet.
4. Verify that your project ID is correct. You can find it on the Settings page of Clarity dashboard.

Example:

final config = ClarityConfig(
  projectId: "your_project_id",
  userId: "your_user_id",
  logLevel: LogLevel.Verbose,
);

Known Limitations

• Offline session data upload is NOT supported at the moment; only session data captured while the user is online is sent.
• Native view capturing (including web views) is NOT supported at the moment; you should find these views covered in recordings.
• Font support is limited at the moment; you might find font differences in the recordings.

If you have any questions or need further assistance, feel free to contact the Clarity Apps team on [e-mail].