coolfix_flutter 0.3.3

CoolFix support inquiry and replay SDK for Flutter applications.

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

CoolFix.start의 런타임 설정 HTTP 요청 timeout은 10초입니다. 설정 요청 실패, 녹화 시작 실패, 오프라인 등으로 생긴 시작 오류를 호출자에게 전파하지 않습니다. 따라서 오류로 앱 시작을 실패시키지는 않습니다. 하지만 runApp 전에 await CoolFix.start(...)하면 완료될 때까지 첫 프레임을 지연할 수 있습니다. 10초는 런타임 설정 HTTP 요청에만 적용되고 이후 캡처 시작도 기다리므로 전체 시작 시간이 항상 10초 이내라고 보장되지 않습니다. 앱의 시작 정책에 맞춰 실제 기기에서 시작 시간과 첫 프레임 영향을 측정하세요. 실패한 시작을 SDK가 자동으로 재시도하지 않습니다. 다음 앱 실행에서 다시 시작하거나 앱이 자체적으로 안전한 재호출 시점을 정해야 합니다.

App Token 누락 정책은 호스트 앱이 선택합니다. 운영에 필수라면 위 예시처럼 시작 전에 실패시키고, 선택적 고객지원이라면 토큰이 없을 때 앱은 시작하되 문의 진입점을 비활성화합니다. CoolFix.start 자체는 빈 토큰을 검증하지 않습니다.

identify와 reset은 캡처 계층 오류를 호출자에게 전파하지 않습니다. 따라서 CoolFix 연결 때문에 로그인, 로그아웃 또는 계정 삭제를 되돌리지 마세요. 복원된 기존 세션과 사용자 전환을 중앙 인증 상태에서 연결하고, 같은 사용자 ID의 불필요한 중복 호출은 피합니다.

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.

개발 중 실제 CoolFix 테스트 문의를 보내지 마세요. 로컬 녹화 preview API는 없으므로 실기기에서 민감한 위젯을 직접 확인합니다. 서버 연계 대시보드 검증이 꼭 필요하면 명시적으로 승인된 비운영 앱·환경에서만 검증합니다.

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:

Future<void> openCoolFixInquiry(BuildContext context) async {
  try {
    await CoolFix.presentInquiry(context);
  } catch (_) {
    debugPrint('CoolFix inquiry could not be opened.');
    if (!context.mounted) return;
    ScaffoldMessenger.of(context).showSnackBar(
      const SnackBar(content: Text('고객 지원을 열 수 없습니다. 잠시 후 다시 시도해 주세요.')),
    );
  }
}

실시간 상담 identity를 불러오지 못하면 presentInquiry가 화면 이동 전에 오류로 완료될 수 있습니다. 문의 UI 경계에서 이 호출을 catch하고 안전한 사용자 메시지를 표시하며 오류를 로깅하세요. 이 실패 때문에 인증이나 다른 핵심 앱 동작을 되돌리지 마세요.

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://app.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);

submitInquiry는 잘못된 입력, 미시작, 인증 실패, rate limit, 네트워크 및 서버 실패를 CoolFixException으로 보고합니다. 관리형 문의 화면은 전송 중 중복 제출을 막고 실패 뒤 초안을 보존하며 안전한 사용자 메시지를 표시합니다. SDK는 실패한 문의를 자동 재시도하지 않으므로 사용자가 네트워크 복귀 뒤 다시 제출해야 합니다. 기존 문의 UI가 submitInquiry를 직접 호출한다면 같은 오류 경험을 제공하세요.

현재 로컬 녹화 preview API는 없습니다. 실제 CoolFix 서버로 테스트 문의를 보내지 말고 앱의 mock 문의 경계로 자동 테스트합니다. 마스킹은 실기기에서 민감 화면을 조작해 확인하고, 서버 연계 결과가 꼭 필요하면 승인된 비운영 앱·환경에서만 검증합니다.

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.