UniApp 앱 연동¶
문서 소개¶
이 문서는 UniApp RUM SDK의 시작 페이지로서 최초 연동에 필요한 정보, 설치 방식, 읽기 경로, 상세 설정 진입점, 고급 시나리오 진입점 및 FAQ를 담고 있습니다.
매개변수 표, API 설명, 수동 수집 예시 및 런타임 기능이 필요한 경우 아래 주제별 페이지에서 확인하십시오.
읽기 경로¶
다음 순서대로 읽는 것을 권장합니다.
0.2.x에서 업그레이드하는 경우 먼저 UniApp 0.3.0 마이그레이션 가이드를 읽으십시오.- 최초 연동 시 먼저 연동 방식 선택을 진행하고, 수동 연동은 빠른 시작을 참고하십시오.
- 실제 연동 방식에 따라 설치를 완료합니다.
- SDK 초기화를 완료한 후 SDK 초기화 및 RUM 설정을 계속 읽으십시오.
- 로그 수집과 분산 추적이 필요한 경우 Log 설정 및 Trace 설정을 계속 읽으십시오.
- 태그, 마스킹 또는 WebView 수집이 필요한 경우 해당 고급 주제를 계속 읽으십시오.
사전 요구 사항¶
uni-app 앱에서 GC-UniPlugin 0.3.0 이상 버전을 연동할 때는 HBuilderX 4.25.0 이상을 사용합니다.
참고: RUM Headless 서비스를 이미 활성화한 경우 사전 요구 사항이 자동으로 구성되었으므로 바로 앱 연동을 시작할 수 있습니다.
로컬 환경 배포를 사용하는 경우 다음 데이터 수신단 설정을 완료해야 합니다. 퍼블릭 DataWay를 사용하는 경우에는 DataKit을 직접 배포할 필요가 없습니다.
- DataKit 설치;
- RUM 수집기 설정;
- DataKit을 퍼블릭 네트워크에서 접근 가능하게 구성하고 IP 지리 정보 라이브러리 설치합니다.
앱 연동¶
- RUM > 앱 생성으로 이동합니다.
- 실제 배포 플랫폼에 따라 Android, iOS, HarmonyOS 앱을 각각 생성합니다.
- 각 플랫폼에 해당하는
RUM App ID를 저장하고, RUM 초기화 시 각각androidAppId,iOSAppId,harmonyAppId를 전달합니다. - "연동 방식 선택"에서 Agent 자동 연동 또는 수동 연동을 선택한 다음 "연동 설정"을 완료합니다.
연동 방식 선택¶
앱 설정 페이지에서 "Agent 자동 연동" 또는 "수동 연동"을 선택한 다음 "연동 설정"을 완료합니다. 기존 앱은 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 경로 |
|---|---|---|
| Agent 자동 연동 | 코딩 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하도록 하려는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 앱 코드 저장소에서 코딩 어시스턴트에 전달해 실행 |
| 수동 연동 | SDK를 직접 설치하고 매개변수를 설정하려는 경우 | 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 설정 완료 |
Agent 자동 연동¶
- 현재 앱의 설정 페이지에서 "Agent 자동 연동"을 선택합니다.
- "연동 설정"의 전체 프롬프트를 복사하고, 현재 앱의 연동 정보를 사용해야 합니다.
- 앱 코드 저장소에서 코딩 어시스턴트를 열고 프롬프트를 붙여넣으면 Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 설정을 완료합니다.
- 앱을 빌드하고 실행하여 페이지 방문 등의 작업을 수행한 뒤, 현재 앱의 탐색기에서 데이터 수신을 확인합니다.
크로스 플랫폼 프레임워크를 사용하는 경우 Agent에 프레임워크와 대상 플랫폼을 설명하고, 각 플랫폼에 해당하는 앱 정보를 각각 제공하십시오.
페이지에 개인 API Key 또는 임시 인증 코드가 준비되지 않았다고 표시되면, 안내에 따라 보완한 후 프롬프트를 다시 복사하십시오.
수동 연동¶
앱 설정 페이지에서 "수동 연동"을 선택하고 데이터 보고 방식을 확인합니다.
- 퍼블릭 DataWay:
datawayUrl및clientToken을 준비합니다. - 로컬 환경 배포:
datakitUrl을 준비합니다.
아래 설치 및 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 기존 SDK 설정이 있는 경우 먼저 확인하여 재사용하고 중복 초기화를 피해야 합니다.
설치¶
로컬 사용¶
소스 코드 주소: 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 // 호스트 App에서 사용하는 GC-UniPlugin 네이티브 종속성 라이브러리
SDK 소스 코드 저장소의 해당 버전 Hbuilder_Example/uni_modules에서 다음 디렉터리를 비즈니스 프로젝트의 uni_modules로 복사합니다.
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 브리지 로드¶
앱 진입점에서 setup.js를 가장 먼저 한 번 로드합니다.
SDK API는 HBuilderX가 UTS interface를 기반으로 제공하는 타입 검사와 매개변수 힌트를 받을 수 있도록 GC-UniPlugin에서 가져오고, 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 리소스 패키지로 제작하여 호스트 App에서 실행되는 프로젝트를 특정하며, WeChat, Alipay 등의 플랫폼 미니프로그램을 통칭하지 않습니다.
uni 미니프로그램 SDK 설치는 uni 미니프로그램 프로젝트와 호스트 App 두 부분으로 구성됩니다.
| 연동 위치 | 설치 내용 | 주요 역할 |
|---|---|---|
| uni 미니프로그램 프로젝트 | GC-JSPlugin |
공용 JS API를 제공하고 View, Error, Resource, Action을 수집 |
| 호스트 App | Native SDK + uni 미니프로그램 호스트 확장 | SDK를 초기화하고 네이티브 데이터를 수집하며 uni 미니프로그램에 네이티브 Module 제공 |
개발 디버깅 및 wgt 배포 사용¶
개발 디버깅 및 wgt 리소스 패키지 제작 시 uni 미니프로그램 프로젝트에는 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부터 새로 연동하는 프로젝트는 호스트 App이 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에서 업그레이드를 참고하십시오.
호스트 App 통합¶
호스트 App은 해당 플랫폼의 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 미니프로그램이 공용 JS API 또는 uni.requireNativePlugin()을 통해 네이티브 기능을 호출할 수 있도록 uni 미니프로그램 런타임 환경에 다음 모듈 ID를 등록해야 합니다.
호스트 App은 플랫폼별로 다음 종속성 통합 및 Module 등록 작업을 완료해야 합니다.
iOS¶
-
종속성 라이브러리를 추가합니다.
호스트 App은 iOS Native SDK 설치 안내에 따라 Native SDK를 통합해야 합니다. Swift Package Manager를 사용하고
GuanceSDKPackage Product를 호스트 App Target에 추가하는 것을 권장합니다. Native SDK 버전은 UniApp SDK 릴리스 버전과 일치해야 하며, 구체적인 버전은 해당 버전의 릴리스 노트를 참고하십시오.배포 패키지의
GC-UniPlugin-App.xcframework를 호스트 App Target에 추가합니다. Xcode의TARGETS -> Build Phases -> Link Binary With Libraries에서 "+"를 클릭하고Add Other -> Add Files...를 선택한 다음 해당 파일을 선택합니다. 이 XCFramework는 정적 라이브러리이므로TARGETS -> General -> Frameworks, Libraries, and Embedded Content에서Do Not Embed를 유지합니다. -
앱 시작 시
GCUniPluginModule을 등록합니다.- (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()에서GCUniPluginModule을 등록합니다.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는 호스트 App에서 제공하며 Mobile, RUM, Log, Trace의 초기화 설정을 포함합니다. uni 미니프로그램은 해당 초기화 API를 다시 호출하지 않습니다.
초기화 및 디버깅¶
호스트 App은 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 페이지와 수집 로직 디버깅에만 사용되며 네이티브 데이터 보고를 검증할 수 없습니다. 전체 통합 테스트는 실제 호스트 App에서 수행해야 합니다.
0.2.x에서 업그레이드¶
0.3.0은 일반 uni-app과 uni 미니프로그램에 서로 다른 마이그레이션 방식을 적용합니다. 일반 uni-app은 GC-UniPlugin으로 기존 네이티브 플러그인을 대체하고, uni 미니프로그램 프로젝트는 계속 GC-JSPlugin만 통합하며 호스트 App이 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 플러그인 내부에서 구현됩니다.
따라서 오프라인 패키징은 일반적으로 더 완전한 Native 자동 수집 기능을 사용할 수 있습니다. sdkConfig에서는 offlinePackage를 통해 두 패키징 방식을 구분합니다.
- Android 클라우드 패키징: 기본값
false를 유지합니다. - Android 오프라인 패키징:
true로 설정합니다. - 기존
0.2.xuni 미니프로그램 프로젝트에서 여전히 JS 측에서sdkConfig()를 호출하는 경우:true로 설정합니다. 0.3.0이상 버전의 새 uni 미니프로그램 연동은 호스트 App이 SDK를 초기화하므로 이 매개변수와 관련이 없으며, uni 미니프로그램은sdkConfig()를 다시 호출하지 않습니다.
오프라인 패키징 또는 uni 미니프로그램 호스트 App에서 앱 시작, Native 페이지, 클릭, 네트워크 요청 및 WebView 데이터를 수집하려면 호스트 프로젝트에서 Android Gradle Plugin도 설정해야 합니다.
기타¶
- Android 개인정보 보호 심사
- iOS 기타 관련
- Android 기타 관련
- 네이티브 심볼 파일 업로드: Android, iOS