콘텐츠로 이동

Flutter 애플리케이션 연동


각 Flutter 애플리케이션의 메트릭 데이터를 수집하여 애플리케이션 측 성능을 시각화된 방식으로 분석합니다.

읽기 경로

사전 조건

주의: RUM Headless 서비스를 활성화한 경우 사전 조건이 자동으로 설정되어 있으므로 애플리케이션을 바로 연동하면 됩니다.

로컬 환경에 배포하는 경우 다음 데이터 수신 측 설정을 완료해야 합니다. 공용 네트워크 DataWay를 사용하는 경우 DataKit을 직접 배포할 필요가 없습니다.

애플리케이션 연동

주의

현재 Flutter 버전은 Android 및 iOS 플랫폼만 지원합니다.

  1. RUM > 앱 생성 > Android/iOS로 이동합니다.
  2. Flutter Android용과 Flutter iOS용 애플리케이션을 각각 생성하여 Android 및 iOS 플랫폼에서 오는 RUM 데이터를 각각 수신합니다.
  3. 각 플랫폼 애플리케이션에 해당하는 애플리케이션 이름과 애플리케이션 ID를 입력합니다.
  4. 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 설정」을 완료합니다.

Flutter Web 프로젝트

ft_mobile_agent_flutter는 현재 Android / iOS 네이티브 브리지 기능만 제공하며 Flutter Web bridge는 제공하지 않습니다.

애플리케이션이 Flutter Web에서 실행되는 경우 Web 유형의 RUM 애플리케이션을 생성하고 Web 애플리케이션 연동에 따라 Browser RUM SDK를 사용하세요. 이 방식은 Browser RUM SDK 연동에 해당하며, 이 문서 뒷부분의 Android / iOS 네이티브 브리지 API를 사용하지 않고 Dart 코드에서 ft_mobile_agent_flutter를 호출하여 Web RUM을 초기화할 필요도 없습니다.

Flutter Web 프로젝트의 연동 위치는 일반적으로 프로젝트 루트 디렉터리의 web/index.html이며, Flutter 시작 스크립트 앞에서 Browser RUM SDK 또는 비즈니스 측 초기화 스크립트를 로드할 수 있습니다. build/web 디렉터리는 수정하지 마세요. 이 디렉터리는 Flutter 빌드 산출물이며 flutter build web을 실행하면 다시 생성됩니다.

연동 방식 선택

애플리케이션 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 설정」을 완료합니다. 기존 애플리케이션은 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.

연동 방식 사용 사례 작업 진입점
Agent 자동 연동 코딩 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하도록 하려는 경우 콘솔에서 생성된 프롬프트를 복사하여 애플리케이션 코드 저장소에서 코딩 어시스턴트에 전달해 실행합니다
수동 연동 SDK를 직접 설치하고 파라미터를 설정하려는 경우 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 설정을 완료합니다

Agent 자동 연동

  1. 현재 애플리케이션의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
  2. 「연동 설정」의 전체 프롬프트를 복사하고, 현재 애플리케이션의 연동 정보를 사용해야 합니다.
  3. 애플리케이션 코드 저장소에서 코딩 어시스턴트를 열고 프롬프트를 붙여넣으면 Agent가 연동 안내에 따라 프로젝트를 분석하고 SDK 설정을 완료합니다.
  4. 애플리케이션을 빌드 및 실행하고 페이지 방문 등의 작업을 트리거한 뒤, 현재 애플리케이션의 탐색기에서 데이터 수신을 확인합니다.

크로스 플랫폼 프레임워크를 사용하는 경우 Agent에 프레임워크와 대상 플랫폼을 설명하고, 각 플랫폼에 해당하는 애플리케이션 정보를 각각 제공하세요.

페이지에 개인 API Key 또는 임시 인증 코드가 준비되지 않았다는 안내가 표시되면 안내에 따라 보완한 후 프롬프트를 다시 복사하세요.

수동 연동

애플리케이션 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다.

  • 공용 네트워크 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.
  • 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.

아래 설치 및 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료하세요. 기존 SDK 설정이 있는 경우 먼저 확인하고 재사용하여 중복 초기화를 방지해야 합니다.

설치

Pub.Dev: ft_mobile_agent_flutter

소스 코드 주소: https://github.com/GuanceCloud/datakit-flutter

Demo 주소: https://github.com/GuanceCloud/datakit-flutter/example

프로젝트 경로에서 다음을 실행합니다:

flutter pub add ft_mobile_agent_flutter

그러면 패키지의 pubspec.yaml에 종속성이 추가됩니다:

dependencies:
  ft_mobile_agent_flutter: [latest_version]

  # flutter 2.0 호환 버전은 아래 참조 방식을 사용합니다
  ft_mobile_agent_flutter:
    git:
url: https://github.com/GuanceCloud/datakit-flutter.git
ref: [github_legacy_lastest_tag]

Dart 코드에서 다음과 같이 가져옵니다:

import 'package:ft_mobile_agent_flutter/ft_mobile_agent_flutter.dart';

ft_mobile_agent_flutter 0.5.7부터 Session Replay는 독립 패키지 ft_session_replay_flutter에서 제공됩니다. 세션 리플레이를 활성화하려면 Flutter 세션 리플레이를 계속 읽어 보세요.

Android 연동 추가 설정

  • Gradle Plugin ft-plugin을 설정하여 App 시작 이벤트 및 Android Native 관련 이벤트(페이지 이동, 클릭 이벤트, Native 네트워크 요청, WebView 데이터)를 수집합니다.
  • 시작 횟수와 시작 시간을 집계하려면 Flutter 버전에 따라 Application을 사용자 정의하고 onCreate()를 재정의한 후 super.onCreate()를 호출하고, AndroidManifest.xml에 선언해야 합니다.
  • 사용자 정의 Application은 반드시 ft-plugin 계측에 포함되어야 합니다. 플러그인이 기본적으로 제외하는 com.ft.sdk 패키지 및 하위 패키지에 두지 말고, 제외 규칙으로 해당 클래스를 건너뛰지 마세요. 포그라운드/백그라운드 상태 기록도 올바른 연동에 의존합니다.

Flutter 3.28.x 이하 버전은 이전 작성 방식을 사용합니다:

import io.flutter.app.FlutterApplication

/**
 * 시작 횟수와 시작 시간을 집계하려면 여기에 사용자 정의 Application을 추가해야 합니다
 */
class CustomApplication : FlutterApplication() {
    override fun onCreate() {
        super.onCreate()
    }
}

Flutter 3.29.0 이상 버전은 새로운 작성 방식을 사용합니다:

import android.app.Application

/**
 * 시작 횟수와 시작 시간을 집계하려면 여기에 사용자 정의 Application을 추가해야 합니다
 */
class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
    }
}
Flutter 3.29.0 이상 버전 주의 사항

Flutter 3.29.0에서는 io.flutter.app.FlutterApplication을 포함한 v1 Android embedding이 제거되었으므로, 이 버전부터는 위의 새로운 작성 방식으로 변경해야 합니다. Android App 시작 이벤트를 수집하려면 ft-plugin이 사용자 정의 Application의 onCreate()에 시작 리스너 코드를 삽입해야 합니다. android.app.Application(또는 androidx.multidex.MultiDexApplication)을 직접 상속하지 않으면 launch_cold 등의 App 시작 이벤트가 수집되지 않을 수 있습니다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.flutter.agent_example">
  <application android:name=".CustomApplication">
    //...
  </application>
</manifest>

iOS 연동

SDK 0.5.8부터 Swift Package Manager를 지원하며 iOS 15.0 이상이 필요합니다.

SDK는 CocoaPods와 Swift Package Manager 연동 방식을 모두 제공합니다. iOS 네이티브 종속성은 GuanceSDK1.6.9로 업그레이드되며 Flutter 플러그인에서 선언하고 해석합니다. 프로젝트가 여전히 이전 FTMobileSDK에 직접 의존하는 경우 해당 종속성을 확인하고 마이그레이션하여 두 SDK가 동시에 링크되지 않도록 해야 합니다.

CocoaPods

애플리케이션 ios/Podfile의 플랫폼 버전과 Xcode에서 애플리케이션 및 관련 Extension의 Deployment Target을 15.0 이상으로 설정합니다:

-platform :ios, '12.0'
+platform :ios, '15.0'

애플리케이션 디렉터리에서 flutter pub get을 실행한 다음 ios 디렉터리에서 pod install을 실행하여 플러그인 및 네이티브 SDK 종속성을 업데이트합니다.

Swift Package Manager

Flutter 3.44 이상 버전을 사용하고 애플리케이션 pubspec.yaml에서 Swift Package Manager를 활성화합니다:

flutter:
  config:
    enable-swift-package-manager: true

flutter pub get을 실행한 후 flutter run 또는 flutter build ios를 통해 Flutter의 Swift Package Manager 통합을 완료합니다. Xcode 애플리케이션 및 관련 Extension의 Deployment Target이 15.0 이상인지 확인하세요. 플러그인의 네이티브 SDK를 애플리케이션 Target에 수동으로 중복 추가할 필요는 없습니다.

상세 설정 진입점

고급 시나리오

충돌 필드 설명

  • 특수 키: track_id는 추적 기능에 사용됩니다.
  • 사용자가 globalContext를 통해 추가한 사용자 정의 태그가 SDK 자체 태그와 동일한 경우 SDK 태그가 사용자가 설정한 값을 덮어씁니다.
  • 태그 이름에는 프로젝트 약어 접두사를 추가하는 것이 좋습니다. 예: custom_tag_name

  • 프로젝트에서 사용하는 key 값은 Android 상수 정의 Constants.java를 참고하세요.

자주 묻는 질문

문서 평가

이 페이지가 도움이 되었나요?