UniApp 애플리케이션 연동¶

문서 개요¶

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

매개변수 표, API 설명, 수동 수집 예제 및 런타임 기능이 필요하면 아래의 주제별 페이지를 참조하십시오.

읽기 경로¶

다음 순서로 읽을 것을 권장합니다.

0.2.x에서 업그레이드하는 경우, 먼저 UniApp 0.3.0 마이그레이션 가이드를 읽으십시오.
최초 연동은 먼저 빠른 시작을 읽으십시오.
실제 연동 방식에 따라 설치를 완료하십시오.
SDK 초기화를 완료한 후, SDK 초기화 및 RUM 설정을 계속 읽으십시오.
로그 수집 및 분산 추적이 필요하면, Log 설정 및 Trace 설정을 계속 읽으십시오.
태그, 데이터 마스킹 또는 WebView 수집이 필요하면, 해당 고급 주제를 계속 읽으십시오.

전제 조건¶

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

DataKit 설치
RUM 수집기 구성
DataKit을 공개망에서 액세스 가능하도록 구성하고 IP 지리 정보 데이터베이스 설치
uni-app 애플리케이션이 GC-UniPlugin 0.3.0 이상 버전을 사용하는 경우, HBuilderX 4.25.0 이상 사용

애플리케이션 연동¶

실제 사용자 모니터링(RUM) > 새 애플리케이션으로 이동
실제 게시 플랫폼에 따라 각각 Android, iOS, HarmonyOS 애플리케이션 생성
각 플랫폼에 해당하는 RUM App ID를 저장하고, RUM 초기화 시 각각 androidAppId, iOSAppId, harmonyAppId 전달
데이터 전송 방식 선택:
공용 DataWay: datawayUrl 및 clientToken 준비
로컬 환경 배포: datakitUrl 준비

설치¶

로컬 사용¶

소스 코드 주소: GuanceCloud/datakit-uniapp-native-plugin

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

|-- datakit-uniapp-native-plugin
  |-- Hbuilder_Example                         // HBuilderX 예제 프로젝트 및 바로 사용 가능한 uni_modules
    |-- uni_modules
      |-- GC-JSPlugin                         // JS 자동 수집
        |-- js_sdk
          |-- Action/GCActionTracking.js      // HarmonyOS 측 Action 자동 수집
          |-- Error/GCErrorTracking.js        // Error 자동 수집
          |-- Request/GCResourceTracking.js   // uni.request Resource 및 Trace 자동 수집
          |-- View/GCViewTracking.js          // 권장 View 전역 자동 수집기
        |-- index.js
        |-- package.json
      |-- GC-UniPlugin                        // Android, iOS, HarmonyOS UTS 메인 플러그인
        |-- utssdk
        |-- setup.js                          // JS 수집기와 UTS SDK 간 브리지 설정
        |-- package.json
      |-- GC-UniSessionReplay                 // 선택적 Android, iOS Session Replay 플러그인
  |-- native-projects                         // 네이티브 빌드, 패키징 및 통합 검증 프로젝트
  |-- dist                                    // 외부 배포 산출물
    |-- native-sdk-hybrid                     // uni-app 애플리케이션 오프라인 패키징 산출물
    |-- unimp-host-extension                  // 호스트 앱에서 사용하는 GC-UniPlugin 네이티브 종속 라이브러리

SDK 소스 코드 저장소의 해당 버전 Hbuilder_Example/uni_modules에서 다음 디렉터리를 비즈니스 프로젝트의 uni_modules로 복사합니다.

uni_modules/
├── GC-JSPlugin
└── GC-UniPlugin

Session Replay가 필요하면 선택적 GC-UniSessionReplay를 추가로 설치합니다. Session Replay는 현재 Android 및 iOS만 지원합니다.

설치된 모든 모듈은 동일한 릴리스 버전을 사용해야 합니다. 업그레이드 시 함께 교체하고, 다른 버전의 JS, UTS 또는 Session Replay 모듈을 혼용하지 마십시오.

GC-UniPlugin은 0.3.0부터 새로 추가되어 기존 nativeplugins/GCUniPlugin 네이티브 플러그인을 대체합니다. UTS 모듈이므로 nativeplugins에 복사할 필요가 없으며, manifest.json에서 기존 로컬 네이티브 플러그인을 등록할 필요도 없습니다. GC-JSPlugin은 계속해서 공용 JS API 및 수집기를 제공합니다.

UTS Bridge 로드¶

애플리케이션 진입점에서 가장 먼저 setup.js를 한 번 로드합니다.

import '@/uni_modules/GC-UniPlugin/setup.js';

SDK API는 GC-UniPlugin에서 가져와 HBuilderX가 UTS interface 기반으로 제공하는 타입 검사 및 매개변수 힌트를 활용합니다. JS 수집기는 GC-JSPlugin에서 가져옵니다.

import {
    mobileAgent,
    rum,
    logger,
    tracer
} from '@/uni_modules/GC-UniPlugin';

import {
    gcErrorTracking,
    gcViewTracking,
    gcResourceTracking,
    gcActionTracking
} from '@/uni_modules/GC-JSPlugin';

마켓 플러그인 방식¶

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

uni 미니 프로그램 SDK 설치¶

이 절의 "uni 미니 프로그램"은 uni-app으로 개발하고 HBuilderX로 wgt 리소스 패키지로 제작하여 호스트 앱에서 실행되는 프로젝트를 지칭하며, WeChat, Alipay 등의 플랫폼 미니 프로그램을 일반적으로 지칭하지 않습니다.

uni 미니 프로그램 SDK 설치는 uni 미니 프로그램 프로젝트와 호스트 앱 두 부분으로 구성됩니다.

연동 위치	설치 내용	주요 역할
uni 미니 프로그램 프로젝트	`GC-JSPlugin`	공용 JS API 제공, View, Error, Resource 및 Action 수집
호스트 앱	Native SDK + uni 미니 프로그램 호스트 확장	SDK 초기화, 네이티브 데이터 수집, uni 미니 프로그램에 네이티브 Module 제공

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

개발 디버깅 및 wgt 리소스 패키지 제작 시, uni 미니 프로그램 프로젝트는 GC-JSPlugin만 설치합니다.

uni_modules/
└── GC-JSPlugin

GC-JSPlugin은 전체 디렉터리로 제공되며, SDK 저장소의 소스 디렉터리는 Hbuilder_Example/uni_modules/GC-JSPlugin/입니다. 이 디렉터리를 uni 미니 프로그램 프로젝트의 uni_modules/에 복사합니다. 최종 경로는 uni_modules/GC-JSPlugin/이어야 합니다.

uni 미니 프로그램 프로젝트에는 GC-UniPlugin을 설치하거나 가져오지 말고, GC-UniPlugin/setup.js도 로드하지 마십시오. 그렇지 않으면 UTS 코드가 프로젝트 컴파일 종속성에 포함됩니다.

SDK 객체와 JS 수집기는 GC-JSPlugin에서 통일하여 가져옵니다.

import {
    mobileAgent,
    rum,
    logger,
    tracer,
    gcErrorTracking,
    gcViewTracking,
    gcResourceTracking,
    gcActionTracking
} from '@/uni_modules/GC-JSPlugin';

0.3.0부터 새로 연동하는 프로젝트는 호스트 앱에서 SDK 및 RUM, Log, Trace 초기화를 완료합니다. uni 미니 프로그램은 mobileAgent.sdkConfig(), rum.setConfig(), logger.setConfig() 또는 tracer.setConfig()를 중복 호출하지 않고, 다음 런타임 API만 호출합니다.

bindRUMUserData(), unbindRUMUserData()
appendGlobalContext(), appendRUMGlobalContext(), appendLogGlobalContext(), appendBridgeContext()
rum, logger, tracer가 제공하는 수동 데이터 수집 및 Header 획득 API

기존 0.2.x uni 미니 프로그램 프로젝트를 업그레이드하는 경우, 기존 초기화 방식을 유지하고 uni.requireNativePlugin()을 계속 사용하여 Module을 획득할 수 있으며, 비즈니스 코드를 즉시 수정할 필요는 없습니다.

const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');

새 프로젝트는 GC-JSPlugin에서 통일하여 가져오는 것을 권장합니다. 이전 버전의 구체적인 마이그레이션 방식은 0.2.x에서 업그레이드를 참조하십시오.

호스트 앱 통합¶

호스트 앱은 해당 플랫폼의 Native SDK 및 0.3.0 이상 버전의 uni 미니 프로그램 호스트 확장을 통합해야 합니다.

호스트 플랫폼	호스트 확장 형태	게시 산출물	SDK 저장소의 게시 경로
Android	Android UniModule	`gc-uniplugin-<version>.aar`	`dist/unimp-host-extension/android/`
iOS	`DCUniModule`	`GC-UniPlugin-App.xcframework`	`dist/unimp-host-extension/ios/`
HarmonyOS	ETS 네이티브 확장	`GCUniPlugin.har`	`dist/unimp-host-extension/harmony/`

게시 산출물 이름은 사용 중인 버전 릴리스 패키지의 실제 파일명을 기준으로 합니다.

호스트 확장은 uni 미니 프로그램 실행 환경에 다음 모듈 ID를 등록하여, uni 미니 프로그램이 공용 JS API 또는 uni.requireNativePlugin()을 통해 네이티브 기능을 호출할 수 있도록 해야 합니다.

GCUniPlugin-MobileAgent
GCUniPlugin-RUM
GCUniPlugin-Logger
GCUniPlugin-Tracer

호스트 앱은 플랫폼별로 다음 종속성 통합 및 Module 등록 작업을 완료해야 합니다.

iOS¶

종속 라이브러리 추가.

호스트 앱은 iOS Native SDK 설치 설명에 따라 Native SDK를 통합해야 합니다. Swift Package Manager 사용을 권장하며, GuanceSDK Package Product를 호스트 앱 Target에 추가합니다. Native SDK 버전은 UniApp SDK 릴리스 버전과 일치해야 하며, 구체적인 버전은 해당 버전의 업데이트 로그를 참조하십시오.

릴리스 패키지의 GC-UniPlugin-App.xcframework를 호스트 앱 Target에 추가합니다. Xcode의 TARGETS -> Build Phases -> Link Binary With Libraries에서 "+"를 클릭하고 Add Other -> Add Files...를 선택한 후 해당 파일을 선택합니다. 이 XCFramework는 정적 라이브러리이며, TARGETS -> General -> Frameworks, Libraries, and Embedded Content에서 Do Not Embed를 유지합니다.

애플리케이션 시작 시 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¶

종속 라이브러리 추가:

릴리스 패키지의 gc-uniplugin-<version>.aar를 호스트 프로젝트의 libs 디렉터리에 복사합니다. Android Native SDK Gradle 설정에 따라 Maven 저장소를 추가하고, build.gradle에 다음 종속성을 추가합니다.
```
dependencies {
    implementation files('libs/gc-uniplugin-<version>.aar')
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:<version>'
    implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:<version>'
    implementation 'com.alibaba:fastjson:1.2.83'
    implementation 'com.google.code.gson:gson:2.8.5'
}
```
Native SDK 버전은 UniApp SDK 릴리스 버전과 일치해야 하며, 구체적인 버전은 해당 버전의 업데이트 로그를 참조하십시오.

Application.onCreate()에서 GCUniPlugin Module 등록:

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

HarmonyOS¶

GCUniPlugin.har를 호스트 프로젝트의 libs에 넣고, oh-package.json5에 UniMP 런타임 및 로컬 확장 종속성을 추가합니다.

{
    "dependencies": {
        "@dcloudio/uni-app-runtime": "5.2.32026080401",
        "@guancecloud/gc-uniplugin": "file:./libs/GCUniPlugin.har"
    }
}

종속성 추가 후, 프로젝트 디렉터리에서 ohpm install을 실행합니다.

호스트 확장은 initializeNativeSDK() 및 registerNativeModules()를 제공합니다. 호스트는 먼저 UIAbility.onCreate()에서 SDK를 초기화해야 합니다. 그런 다음 init()이 uni 미니 프로그램 실행 환경을 초기화한 후, 처음 uni 미니 프로그램을 열기 전에 모듈을 등록합니다.

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { init } from '@dcloudio/uni-app-runtime';
import {
    initializeNativeSDK,
    registerNativeModules
} from '@guancecloud/gc-uniplugin';
import { SDK_STARTUP_CONFIG } from '../config/SDKStartupConfig';

export default class EntryAbility extends UIAbility {
    onCreate(): void {
        initializeNativeSDK(this.context, SDK_STARTUP_CONFIG);
    }

    onWindowStageCreate(windowStage: window.WindowStage): void {
        init(this, windowStage, { debug: true });
        registerNativeModules(this.context);

        // 그 후에 uni 미니 프로그램을 엽니다.
    }
}

SDK_STARTUP_CONFIG는 호스트 앱에서 제공하며, Mobile, RUM, Log 및 Trace의 초기화 설정을 포함합니다. uni 미니 프로그램은 해당 초기화 API를 중복 호출하지 않습니다.

초기화 및 디버깅¶

호스트 앱은 uni 미니 프로그램을 열기 전에 Native SDK 초기화 및 Module 등록을 완료해야 하며, 최종 애플리케이션에 하나의 Native SDK와 하나의 SDK 싱글톤 세트만 존재하도록 해야 합니다. uni 미니 프로그램은 SDK를 다시 초기화할 필요가 없습니다.

Android 및 iOS 호스트의 Native SDK 초기화 방식은 각각 Android SDK 초기화 및 iOS SDK 초기화를 참조하십시오. HarmonyOS 호스트는 위의 initializeNativeSDK()를 사용하여 초기화를 완료합니다.

uni 미니 프로그램 프로젝트가 호스트 확장이 통합되지 않은 일반 디버깅 베이스에서 실행될 때, GC-JSPlugin은 누락된 네이티브 호출을 no-op으로 대체하여 uni.requireNativePlugin()이 null을 반환하더라도 페이지 로딩을 차단하지 않습니다. 이 모드는 JS 페이지 및 수집 로직 디버깅에만 사용할 수 있으며, 네이티브 데이터 전송을 검증할 수 없습니다. 전체 통합 테스트는 실제 호스트 앱에서 수행해야 합니다.

0.2.x에서 업그레이드¶

0.3.0은 일반 uni-app과 uni 미니 프로그램에 대해 서로 다른 마이그레이션 방식을 사용합니다. 일반 uni-app은 GC-UniPlugin을 사용하여 기존 네이티브 플러그인을 교체합니다. uni 미니 프로그램 프로젝트는 계속 GC-JSPlugin만 통합하고, 호스트 앱이 Native SDK와 호스트 확장을 업그레이드합니다.

전체 종속성 구조, API 가져오기, 초기화 위치, 호환 방식 및 마이그레이션 전후 코드 비교는 UniApp 0.3.0 마이그레이션 가이드를 참조하십시오.

상세 설정 진입¶

설정 설명¶

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

고급 시나리오¶

FAQ¶

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

Android 클라우드 패키징과 오프라인 패키징은 서로 다른 두 가지 통합 로직을 사용합니다. 오프라인 패키징 방식은 Android Native SDK의 통합 방식과 동일하며, 호스트 프로젝트에서 Android Gradle Plugin을 적용할 수 있습니다. 클라우드 패키징은 해당 플러그인을 적용할 수 없으므로, 일부 기능은 UniApp 플러그인 내부에서 구현됩니다.

따라서 오프라인 패키징은 일반적으로 더 완전한 네이티브 자동 수집 기능을 사용할 수 있습니다. sdkConfig에서 offlinePackage를 통해 두 가지 패키징 방식을 구분합니다.

Android 클라우드 패키징: 기본값 false 유지
Android 오프라인 패키징: true로 설정
기존 0.2.x uni 미니 프로그램 프로젝트가 JS 측에서 sdkConfig()를 계속 호출하는 경우: true로 설정
0.3.0 이상 버전의 새 uni 미니 프로그램 연동은 호스트 앱이 SDK를 초기화하므로 이 매개변수와 관련이 없으며, uni 미니 프로그램은 sdkConfig()를 중복 호출하지 않습니다.

오프라인 패키징 또는 uni 미니 프로그램 호스트 앱에서 앱 시작, 네이티브 페이지, 클릭, 네트워크 요청 및 WebView 데이터를 수집해야 하는 경우, 호스트 프로젝트에서 Android Gradle Plugin을 추가로 구성해야 합니다.

UniApp 애플리케이션 연동¶

문서 개요¶

읽기 경로¶

전제 조건¶

애플리케이션 연동¶

설치¶

로컬 사용¶

UTS Bridge 로드¶

마켓 플러그인 방식¶

uni 미니 프로그램 SDK 설치¶

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

호스트 앱 통합¶

iOS¶

Android¶

HarmonyOS¶

초기화 및 디버깅¶

0.2.x에서 업그레이드¶

상세 설정 진입¶

설정 설명¶

고급 시나리오¶

FAQ¶

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

기타¶

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

UniApp 애플리케이션 연동¶

문서 개요¶

읽기 경로¶

전제 조건¶

애플리케이션 연동¶

설치¶

로컬 사용¶

UTS Bridge 로드¶

마켓 플러그인 방식¶

uni 미니 프로그램 SDK 설치¶

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

호스트 앱 통합¶

iOS¶

Android¶

HarmonyOS¶

초기화 및 디버깅¶

0.2.x에서 업그레이드¶

상세 설정 진입¶

설정 설명¶

고급 시나리오¶

FAQ¶

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

기타¶

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

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