CoolFix for Flutter

CoolFix connects customer inquiries, user context, and the relevant session in one support workflow. Your app only needs the CoolFix package and the App Token issued in the CoolFix dashboard.

Start CoolFix before runApp, then wrap the app once with CoolFixApp:

const appToken = String.fromEnvironment('COOLFIX_APP_TOKEN');

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (appToken.trim().isEmpty) {
    throw StateError(
      'COOLFIX_APP_TOKEN is required. Run with --dart-define=COOLFIX_APP_TOKEN=cfx_pub_your_app.',
    );
  }
  await CoolFix.start(appToken);
  runApp(const CoolFixApp(child: MyApp()));
}

Pass the token without committing it to source control:

flutter run --dart-define=COOLFIX_APP_TOKEN=cfx_pub_your_app

No navigation observer or additional service configuration is required.

Hide personal data from capture

CoolFix records the screen so support can see what the customer saw. Static labels, buttons, and body text are captured on purpose — a recording of black boxes is useless.

Recording on/off, sampling rate, text masking, and image masking come from your app's recording settings in the CoolFix dashboard. The app reads them at startup, so a change applies on the next launch — no code change, no new release. Password fields (obscureText) are always hidden, whatever the settings say.

For anything that must stay hidden regardless of those settings, wrap it:

CoolFixMask(child: TextField(controller: _name))
CoolFixMask(child: CircleAvatar(backgroundImage: NetworkImage(photoUrl)))

Image masking only reaches Image widgets. Photos painted through BoxDecoration(image:) or CircleAvatar(backgroundImage:) are never covered by the setting alone — wrap those. The managed CoolFix inquiry screen already masks its own input.

Verify it: submit an inquiry, open the session in the CoolFix dashboard, and confirm the personal parts are covered before you release.

Troubleshoot inquiry availability

Use the flutter run --dart-define=COOLFIX_APP_TOKEN=cfx_pub_your_app command above to provide the App Token at run time; do not commit a token to source control.

The managed inquiry screen distinguishes local startup from server rejection:

  • The canonical snippet above fails fast with a StateError before CoolFix.start when COOLFIX_APP_TOKEN is missing or empty. If a host app instead skips CoolFix.start and submits an inquiry, the local error is notStarted. The customer sees CoolFix를 먼저 시작해 주세요.; provide the token with the command above, then start CoolFix before opening the inquiry screen.
  • If a non-empty token reaches the inquiry POST but the current app does not accept it, the error is unauthorized. The customer sees 앱 연결 설정을 확인해 주세요.; verify the current app's App Token in the CoolFix dashboard, update the run-time define, and retry.

The canonical empty-token outcome is decided before startup. For non-empty tokens, server validity is determined when the inquiry is submitted. CoolFix.start does not report or throw server token validity. If capture or replay session context (캡처/리플레이 세션 맥락) is unavailable, the inquiry still submits without that context; a capture/replay outage is not a reason to disable inquiry submission.

Connect users

Call identify after login succeeds and reset when logout completes. Only pass user properties that your product intends to show in support context.

await CoolFix.identify(
  user.id,
  name: user.name,
  email: user.email,
  properties: {'plan': user.plan},
);

await CoolFix.reset();

Receive inquiries

Open the managed inquiry screen from any context under a Navigator:

await CoolFix.presentInquiry(context);

When your CoolFix administrator enables live support, this screen lets the user choose between leaving a message and starting a live Chatwoot conversation. Live support opens in the SDK's managed web view and uses server-issued identity validation; the host app does not handle Chatwoot credentials. If live support is disabled, the existing message form opens directly.

The SDK contacts https://coolfix.me normally. Live support additionally opens the Chatwoot host returned by CoolFix, so allow that host in any restrictive iOS ATS or Android network-security policy used by the app.

If your app has its own inquiry UI, submit its text directly instead:

final receipt = await CoolFix.submitInquiry(text);

The managed screen prevents duplicate submissions, preserves the draft after a failure, and presents safe loading, success, and error states. Inquiry delivery continues even when session context is temporarily unavailable.

Libraries

coolfix_flutter