UniApp 애플리케이션 연결¶

문서 개요¶

본 문서는 UniApp RUM SDK의 진입 페이지로, 최초 연결 시 필요한 필수 정보, 설치 방법, 읽기 경로, 상세 설정 진입, 고급 시나리오 진입 및 FAQ를 제공합니다.

파라미터 테이블, API 설명, 수동 수집 예시 및 런타임 기능이 필요하신 경우 아래 관련 페이지를 참조하시기 바랍니다.

읽기 경로¶

다음 순서로 읽으시기를 권장합니다.

최초 연결 시 먼저 빠른 시작을 읽어주세요.
실제 연결 방식에 따라 설치를 완료하세요.
SDK 초기화를 완료한 후 SDK 초기화 및 RUM 설정을 계속 읽어주세요.
로그 수집 및 분산 추적이 필요한 경우 Log 설정 및 Trace 설정을 계속 읽어주세요.
태그, 데이터 마스킹 또는 WebView 수집이 필요한 경우 해당 고급 주제를 계속 읽어주세요.

전제 조건¶

참고: RUM Headless 서비스를 이미 활성화한 경우 전제 조건이 자동으로 구성되어 있으므로 바로 애플리케이션 연결을 시작할 수 있습니다.

DataKit 설치
RUM 수집기 설정
DataKit을 공개 네트워크에서 접근 가능하도록 설정하고 IP 지리 정보 데이터베이스 설치

애플리케이션 연결¶

실제 사용자 모니터링(RUM) > 새 애플리케이션 > Android/iOS로 이동합니다.
UniApp Android 및 UniApp iOS에 대해 각각 두 개의 애플리케이션을 생성하여 Android 및 iOS 플랫폼의 RUM 데이터를 각각 수신합니다.
각 플랫폼에 대해 해당 애플리케이션 이름과 애플리케이션 ID를 입력합니다.
애플리케이션 연결 방식을 선택합니다.
공용 네트워크 DataWay: DataKit 설치 없이 RUM 데이터를 직접 수신합니다.
로컬 환경 배포: 전제 조건을 충족하면 로컬 DataKit이 RUM 데이터를 수신합니다.

설치¶

로컬 사용¶

소스 코드 주소: https://github.com/GuanceCloud/datakit-uniapp-native-plugin

Demo 주소: https://github.com/GuanceCloud/datakit-uniapp-native-plugin/Hbuilder_Example

다운로드 후 SDK 패키지 구조는 다음과 같습니다.

|--datakit-uniapp-native-plugin
  |-- Hbuilder_Example
    |-- uni_modules
      |-- GC-JSPlugin
      |   |-- js_sdk
      |   |   |-- View/GCViewTracking.js      // 권장 View 전역 자동 수집기
      |   |   |-- View/GCPageMixin.js         // View 수집 호환, GCWatchRouter.js와 함께 사용 필요
      |   |   |-- View/GCWatchRouter.js       // View 수집 호환, GCPageMixin.js와 함께 사용 필요
      |   |   |-- View/GCPageViewMixinOnly.js // 지정된 페이지만 수집 시 단독 사용
      |   |   |-- Request/GCResourceTracking.js // 표준 uni.request의 Resource 및 Trace 자동 수집기
      |   |   |-- Request/GCRequest.js        // 사용 중단된 Resource 호환 API
      |   |   |-- Error/GCErrorTracking.js   // error 자동 수집, uni.onError, console.error 지원
      |   |-- index.js
      |   |-- package.json
    |-- nativeplugins
      |-- GCUniPlugin
      |   |-- android
      |   |-- ios
      |   |-- package.json
  |-- UniPlugin-Android
  |-- UniPlugin-iOS

GCUniPlugin 디렉토리를 프로젝트의 nativeplugins 디렉토리에 복사하고 manifest.json의 "App 네이티브 플러그인 설정"에서 "로컬 플러그인 선택"을 클릭하여 GCUniPlugin을 선택하세요.

GC-JSPlugin 디렉토리를 프로젝트의 uni_modules 디렉토리에 복사하세요.

참고: 저장 후 반드시 클라우드 패키징을 실행해야 합니다. 커스텀 베이스 제작도 클라우드 패키징에 포함되며, 완료 후 플러그인이 활성화됩니다.

자세한 내용은 HBuilderX에서 로컬 플러그인 사용, 커스텀 베이스를 참조하세요.

마켓 플러그인 방식¶

현재 마켓 플러그인 방식은 제공되지 않습니다. 로컬 사용을 통해 연결을 완료하세요.

uni 미니프로그램 SDK 설치¶

개발 디버깅 및 wgt 게시 사용¶

uni 미니프로그램 SDK는 개발 디버깅 단계에서 로컬 사용 방식으로 GCUniPlugin을 통합해야 합니다.
uni 미니프로그램 SDK를 wgt로 패키징하여 호스트 App에서 사용할 경우, 호스트 App은 GCUniPlugin 종속 라이브러리를 가져와 GCUniPlugin Module을 등록해야 합니다.

호스트 App은 다음 작업을 추가로 수행해야 합니다.

iOS

GCUniPlugin 종속 라이브러리 추가. Xcode의 TARGETS -> Build Phases -> Link Binary With Libraries에서 "+"를 클릭하고 Add Other -> Add Files...를 선택한 후 GCUniPlugin/ios/ 디렉토리를 엽니다. SDK 0.2.7 이상은 GuanceSDK.xcframework 및 GC_UniPlugin_App.xcframework를 추가하고, SDK 0.2.6 이하는 FTMobileSDK.xcframework 및 GC_UniPlugin_App.xcframework를 추가합니다.
SDK 버전이 < 0.2.0인 경우 TARGETS -> General -> Frameworks, Libraries, and Embedded Content에서 FTMobileSDK.xcframework의 Embed 방식을 Embed & Sign으로 변경해야 합니다.
GCUniPlugin Module 등록:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    [WXSDKEngine registerModule:@"GCUniPlugin-MobileAgent" withClass:NSClassFromString(@"FTMobileUniModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-RUM" withClass:NSClassFromString(@"FTRUMModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-Logger" withClass:NSClassFromString(@"FTLogModule")];
    [WXSDKEngine registerModule:@"GCUniPlugin-Tracer" withClass:NSClassFromString(@"FTTracerModule")];
    return YES;
}

Android

GCUniPlugin 종속 라이브러리 추가:
방법 1: GCUniPlugin/android/의 ft-native-[version].aar, ft-sdk-[version].aar, gc-uniplugin-[last-version].aar를 프로젝트 libs 디렉토리에 복사하고 build.gradle에 종속성을 추가합니다.
방법 2: Gradle Maven 원격 저장소 구성을 통해 추가합니다. UniPlugin-Android 프로젝트 설정을 참조하세요.

dependencies {
    implementation files('libs/ft-native-[version].aar')
    implementation files('libs/ft-sdk-[version].aar')
    implementation files('libs/gc-uniplugin-[last-version].aar')
    implementation 'com.google.code.gson:gson:2.8.5'
}

GCUniPlugin Module 등록:

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        try {
            WXSDKEngine.registerModule("GCUniPlugin-Logger", FTLogModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-RUM", FTRUMModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-Tracer", FTTracerModule.class);
            WXSDKEngine.registerModule("GCUniPlugin-MobileAgent", FTSDKUniModule.class);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

UniApp SDK와 Native SDK 혼합 사용¶

호스트 App에 GCUniPlugin을 통합할 때 Native SDK도 함께 가져오므로 Native SDK 메서드를 직접 호출할 수 있습니다.
혼합 사용 시 호스트 App에서만 Native SDK를 초기화하면 됩니다. uni 미니프로그램 측에서는 다시 초기화할 필요 없이 UniApp SDK에서 제공하는 메서드를 직접 호출할 수 있습니다.
호스트 App 초기화 방법은 iOS SDK 초기화 설정 및 Android SDK 초기화 설정을 참조하세요.
uni 미니프로그램을 로드하기 전에 호스트 App에서 SDK 초기화를 반드시 완료하여 이후 메서드 호출 시 SDK가 준비되어 있도록 하세요.

Android 추가 설정

앱 시작 이벤트, 네트워크 요청 및 Android Native 관련 이벤트(페이지 전환, 클릭 이벤트, Native 네트워크 요청, WebView 데이터)를 수집해야 하는 경우 호스트 프로젝트에서 Gradle Plugin ft-plugin을 설정하세요.

uni 미니프로그램과 Native 데이터 구분

SDK 0.2.4 이상 지원

BridgeContext를 사용하여 uni 미니프로그램 측에서 수집한 데이터에 추가 컨텍스트를 추가하여 특정 시나리오를 필터링하거나 연결할 수 있습니다.

예를 들어, wgt_id:wgt_id_1을 사용하여 해당 uni 미니프로그램 데이터를 필터링할 수 있습니다.

var ftModule = uni.requireNativePlugin("GCUniPlugin-MobileAgent");
ftModule.appendBridgeContext({
    'wgt_id': 'wgt_id_1'
});

상세 설정 진입¶

설정 설명¶

빠른 시작: 최초 연결을 위한 최단 경로입니다.
SDK 초기화: 기본 설정, 사용자 바인딩, SDK 종료, 캐시 정리, 능동 동기화.
RUM 설정: RUM 초기화 설정, Action/View/Error/Resource 수집 기능.
Log 설정: Log 초기화 설정 및 로그 출력.
Trace 설정: Trace 초기화 설정 및 분산 추적.

고급 시나리오¶

자주 묻는 질문¶

플러그인 개발 iOS 메인 프로젝트 UniPlugin-iOS 사용¶

UniApp 오프라인 개발 SDK 다운로드¶

uni-app 개발 도구 HBuilderX의 버전 번호에 따라 개발 플러그인에 필요한 SDK 패키지를 다운로드하세요.

SDK 패키지 구조는 다음과 같습니다.

|--iOSSDK
    |-- HBuilder-Hello
    |-- HBuilder-uniPluginDemo
    |-- SDK

종속 라이브러리 및 리소스 파일 SDK 디렉토리를 UniPlugin-iOS로 드래그합니다. 최종 디렉토리 구조는 다음과 같습니다.

|-- UniPlugin-iOS
    |-- HBuilder-uniPluginDemo
    |-- SDK

자세한 내용은 iOS 플러그인 개발 환경 설정을 참조하세요.

프로젝트 설정¶

Architectures 설정 Xcode 12는 arm64 시뮬레이터를 지원하지만 uni-app에서 제공하는 framework는 arm64 실제 기기와 x86_64 시뮬레이터를 지원하므로 Excluded Architectures의 Any iOS Simulator SDK를 arm64로 설정해야 합니다.
Other Linker Flags

$(inherited) -ObjC -framework "GuanceSDK" -framework "GC_UniPlugin_App"

SDK 0.2.6 이하는 여전히 FTMobileSDK framework 이름을 사용합니다.

Framework Search Paths

$(inherited)
"${PODS_CONFIGURATION_BUILD_DIR}/GuanceSDK"
"${PODS_CONFIGURATION_BUILD_DIR}/GC-UniPlugin-App"
$(DEVELOPER_FRAMEWORKS_DIR)
$(PROJECT_DIR)/../SDK/libs
$(PROJECT_DIR)

SDK 0.2.6 이하는 GuanceSDK 경로를 FTMobileSDK로 바꿉니다.

플러그인 개발 Android 메인 프로젝트 UniPlugin-Android 사용¶

프로젝트 설정¶

자세한 종속성 설정은 Demo를 참조하세요. 더 많은 Gradle 확장 파라미터는 Android SDK를 참조하세요.

|-- UniPlugin-Android
    |-- app
        |-- build.gradle
        // apply:'ft-plugin'
    |-- uniplugin_module
        |-- src
            |-- main
                |-- java
                    |-- com.ft.sdk.uniapp
        |-- build.gradle
// implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:xxxx'
// implementation 'com.google.code.gson:gson:xxxx'
// implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:xxxx'
|-- build.gradle
// maven { url 'https://mvnrepo.guance.com/repository/maven-releases' }
        // classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:xxxx'

Android 클라우드 패키징과 오프라인 패키징 차이¶

Android 클라우드 패키징과 오프라인 패키징은 서로 다른 통합 로직을 사용합니다. 오프라인 패키징 방식은 Guance Android SDK 통합 방식과 동일하며 Android Studio Gradle Plugin을 사용할 수 있습니다. 클라우드 패키징은 이 플러그인을 사용할 수 없으므로 일부 기능은 Guance UniApp Native Plugin 내부에서 구현됩니다.

따라서 오프라인 패키징 버전에서 사용할 수 있는 설정 항목이 일반적으로 클라우드 패키징 버전보다 많습니다. sdkConfig의 offlinePackage 파라미터는 이 두 가지 경우를 구분하는 데 사용됩니다. 자세한 내용은 SDK 초기화를 참조하세요.

UniApp 애플리케이션 연결¶

문서 개요¶

읽기 경로¶

전제 조건¶

애플리케이션 연결¶

설치¶

로컬 사용¶

마켓 플러그인 방식¶

uni 미니프로그램 SDK 설치¶

개발 디버깅 및 wgt 게시 사용¶

UniApp SDK와 Native SDK 혼합 사용¶

상세 설정 진입¶

설정 설명¶

고급 시나리오¶

자주 묻는 질문¶

플러그인 개발 iOS 메인 프로젝트 UniPlugin-iOS 사용¶

UniApp 오프라인 개발 SDK 다운로드¶

프로젝트 설정¶

플러그인 개발 Android 메인 프로젝트 UniPlugin-Android 사용¶

프로젝트 설정¶

Android 클라우드 패키징과 오프라인 패키징 차이¶

기타¶

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

UniApp 애플리케이션 연결¶

문서 개요¶

읽기 경로¶

전제 조건¶

애플리케이션 연결¶

설치¶

로컬 사용¶

마켓 플러그인 방식¶

uni 미니프로그램 SDK 설치¶

개발 디버깅 및 wgt 게시 사용¶

UniApp SDK와 Native SDK 혼합 사용¶

상세 설정 진입¶

설정 설명¶

고급 시나리오¶

자주 묻는 질문¶

플러그인 개발 iOS 메인 프로젝트 UniPlugin-iOS 사용¶

UniApp 오프라인 개발 SDK 다운로드¶

프로젝트 설정¶

플러그인 개발 Android 메인 프로젝트 UniPlugin-Android 사용¶

프로젝트 설정¶

Android 클라우드 패키징과 오프라인 패키징 차이¶

기타¶

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

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