Flutter
Sophonz Flutter SDK가 무엇을 수집하는지, Android·Apple SDK 위에서 어떻게 동작하는지, 어떤 패키지로 배포되는지, 이 가이드를 어떤 순서로 읽으면 되는지 정리합니다.
Sophonz Flutter SDK는 Dart에서 일어나는 일 — 오류, 화면 이동, 네트워크 호출, 프레임 드롭, 스팬과 로그 — 을 수집해 그 아래의 Sophonz Android SDK 또는 Sophonz Apple SDK로 넘기는 Flutter 플러그인입니다. 세션 관리, 네이티브 크래시와 ANR 수집, 수집기로의 전송은 네이티브 SDK가 맡으며, 모든 데이터는 OpenTelemetry 형식으로 전달됩니다.
구조
SDK를 쓰는 Flutter 앱에는 두 계층이 함께 동작합니다.
| 계층 | 설정 위치 | 담당 |
|---|---|---|
Dart (sophonz 패키지) | main.dart | Dart 오류, 라우트, HTTP 클라이언트, 프레임·아이솔레이트 멈춤, 직접 기록하는 스팬과 로그 |
| 네이티브 SDK | sophonz-config.json(Android), Sophonz-Info.plist(iOS) | 세션, 기기·앱 리소스, 네이티브 크래시, ANR, 네이티브 네트워크 호출, 저장과 업로드 |
Dart 쪽에는 수집기 주소도 서비스 키도 없습니다. 둘 다 네이티브 설정에서 읽기 때문에, 설치할 때 pubspec.yaml뿐 아니라 android/와 ios/ 폴더도 손봐야 합니다.
CAUTION — 데이터가 도착하느냐는 서비스 키에 달려 있습니다
수집기는 서비스 키를 확인할 수 없는 텔레메트리를 조용히 버립니다. 키 없이 빌드한 앱도 정상적으로 실행되고 수집도 되지만, Sophonz에는 아무것도 도착하지 않습니다. 다른 설정보다 먼저 두 플랫폼 모두에 키를 넣으세요.
수집 항목
Sophonz.instance.start()를 호출하면 Dart 계층이 다음을 수집합니다.
| 신호 | 수집 방식 | 필요한 것 |
|---|---|---|
| 처리되지 않은 Dart·Flutter 오류 | FlutterError.onError와 PlatformDispatcher.onError | start(action: ...) |
| 첫 프레임까지의 시간 | spz-time-to-first-frame-flutter 스팬 | start(action: ...) |
| 느린 프레임, 멈춘 프레임 | 프레임 타이밍. 묶음 info 로그와 warning 로그로 기록 | 없음 |
| UI 아이솔레이트 멈춤 | 이벤트 루프가 700ms 이상 멈추면 spz-dart-isolate-hang 스팬 | 없음 |
| 백그라운드 시간 | spz-app-background 스팬 | 없음 |
| 라우트 | 뷰, 화면 로드 스팬, 상호작용 가능까지의 시간 | SophonzNavigationObserver 또는 SophonzGoRouterObserver |
| HTTP | 보낸 traceparent가 담긴 네트워크 스팬 | SophonzHttpClient 또는 SophonzInterceptor(Dio) |
세션, 네이티브 크래시, ANR(Android), 멈춤(iOS), 앱 시작, 네이티브 코드가 보낸 네트워크 호출은 Dart와 무관하게 네이티브 SDK가 수집합니다. 전체 내용은 계측에 있습니다.
패키지
| 패키지 | 용도 |
|---|---|
sophonz | 앱이 가져다 쓰는 API |
sophonz_dio | Dio 4.x, 5.x 네트워크 수집 |
sophonz_go_router | go_router 6.x~15.x 라우트 추적. StatefulShellRoute 포함 |
sophonz_android, sophonz_ios, sophonz_platform_interface | sophonz가 같은 태그에서 가져옵니다. ErrorCode나 LastRunEndState를 import할 때만 sophonz_platform_interface를 직접 적습니다 |
패키지는 pub.dev가 아니라 sophonz-labs/sophonz-flutter-sdk의 Git 태그로 배포됩니다. 현재 릴리스는 v0.1.0입니다.
요구 사항
| 항목 | 요구 사항 |
|---|---|
| Flutter | 3.22 이상 |
| Dart | 3.4 이상 |
| Android | minSdk 21(26 미만이면 core library desugaring 필요), 앱 모듈에 Sophonz Gradle 플러그인 1.0.0 적용 |
| iOS | 13.0 이상, Sophonz Apple SDK(SophonzIO) 1.0.0 |
읽는 순서
- 설치 — Git 의존성, Android·iOS 연결, 시작 호출
- 설정 —
sophonz-config.json,Sophonz-Info.plist, 서비스 식별, Dart 옵션 - 계측 — 코드 없이 수집되는 항목과 플랫폼별 차이
- 내비게이션 —
Navigator와 go_router의 라우트 추적 - 네트워크 — HTTP 수집과 백엔드로의
traceparent전파 - API 레퍼런스 — 모든 공개 메서드와 플랫폼 지원 여부
- 릴리스 빌드 — 매핑 파일, dSYM, 난독화된 Dart
- 예제 — 전체 앱
- 업그레이드 — 새 릴리스로 옮기기
아직 지원하지 않는 것
NOTE — 0.1.0에서 지원하지 않음
- iOS는 사용자 이름과 이메일을 무시합니다.
setUserName,setUserEmail은 호출은 되지만 iOS에서는 버려집니다. Apple SDK에 해당 공개 API가 없기 때문입니다. 사용자 식별자와 페르소나는 두 플랫폼 모두 동작합니다. - 런타임 익스포터는 Android 전용입니다. iOS에서
addSpanExporter,addLogRecordExporter는 아무 일도 하지 않습니다. iOS 익스포터는 네이티브 시작 옵션에서 지정합니다. - iOS에서는 Flutter 라우트가
app.screen.name을 바꾸지 않습니다. 라우트 뷰와 스팬은 기록되지만, 다른 스팬에는 Flutter 뷰 컨트롤러 이름이 남습니다. - OpenTelemetry API로 만든 스팬은 부모를 잃고,
setStatus,updateName,addLink는 구현되어 있지 않습니다.Sophonz.instance.startSpan에는 이 제약이 없습니다. webview_flutter와의 WebView 세션 공유는 아직 연결되어 있지 않습니다.- Dart 심볼은 업로드되지 않습니다.
--split-debug-info나--obfuscate로 빌드하면 Dart 스택 트레이스를flutter symbolize로 로컬에서 복원해야 합니다.
TIP — 이제 시작입니다
이제 앱을 배포하세요. Sophonz가 실사용자가 겪는 문제를 포착하고, 당신의 앱은 스스로 진화합니다.