UniApp 0.3.0 마이그레이션 가이드¶

이 문서는 0.2.x에서 0.3.0 이상 버전으로 업그레이드하는 프로젝트에 적용됩니다.

먼저 프로젝트의 연동 방식을 확인한 후, 해당 섹션만 읽어주세요.

• uni-app 애플리케이션: HBuilderX로 직접 App을 빌드하는 경우, uni-app 애플리케이션 마이그레이션을 읽어주세요.
• 호스트 앱의 uni 미니 프로그램: uni-app으로 개발하여 wgt 리소스 패키지로 제작한 후 호스트 앱에서 실행하는 경우, 호스트 앱의 uni 미니 프로그램 마이그레이션을 읽어주세요.

아래 diff 코드 블록에서 -는 삭제해야 할 내용, +는 추가해야 할 내용을 나타냅니다.

uni-app 애플리케이션 마이그레이션¶

0.3.0에서 기존 App 네이티브 언어 플러그인 nativeplugins/GCUniPlugin을 대체하는 GC-UniPlugin UTS 플러그인이 새로 추가되었습니다. 업그레이드 시 플러그인 교체와 SDK API 임포트 방식 수정, 두 가지 작업을 완료해야 합니다.

1. App 네이티브 언어 플러그인 교체¶

기존 로컬 네이티브 언어 플러그인을 삭제하고 GC-UniPlugin UTS 플러그인을 설치합니다.

- nativeplugins/GCUniPlugin
+ uni_modules/GC-UniPlugin

마이그레이션 후 디렉터리 구조:

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

다음 작업도 함께 수행합니다.

1. manifest.json에서 nativeplugins/GCUniPlugin에 해당하는 로컬 네이티브 언어 플러그인 구성을 삭제합니다.
2. 동일한 버전의 릴리스 패키지에서 GC-JSPlugin과 GC-UniPlugin을 복사하고, 서로 다른 버전을 혼용하지 마세요.
3. 4.25.0 이상 버전의 HBuilderX를 사용하세요.

0.2.0에서 0.2.3으로 업그레이드하는 경우, 원래 프로젝트에 GC-JSPlugin이 없을 수 있으니 마이그레이션 시 두 모듈을 함께 설치하세요.

nativeplugins/GCUniPlugin과 uni_modules/GC-UniPlugin을 동시에 유지하지 마세요. 그렇지 않으면 SDK 중복, 데이터 중복 수집 또는 네이티브 심볼 충돌이 발생할 수 있습니다.

2. SDK API 임포트 방식 수정¶

uni.requireNativePlugin()을 사용하여 SDK 객체를 가져오는 코드를 삭제하고, GC-UniPlugin에서 임포트하도록 변경합니다.

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ // main.js / main.ts: 한 번만 로드하며, GC-JSPlugin 수집기 호출 전에 배치
+ import '@/uni_modules/GC-UniPlugin/setup.js';
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-UniPlugin';

3. 기존 초기화 코드 유지¶

API 임포트 방식 마이그레이션 후, 기존 초기화 호출은 계속 사용할 수 있습니다.

mobileAgent.sdkConfig(mobileConfig);
rum.setConfig(rumConfig);
logger.setConfig(loggerConfig);
tracer.setConfig(traceConfig);

아래 상황에 따라 관련 파라미터를 확인하기만 하면 됩니다.

샘플링률 파라미터¶

설정에서 samplerate를 사용 중인 경우 sampleRate로 변경하는 것을 권장합니다.

rum.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

logger.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

tracer.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

samplerate는 현재도 호환되지만 더 이상 사용되지 않습니다(deprecated). 두 값을 동시에 설정한 경우 sampleRate가 우선 적용됩니다.

HarmonyOS 애플리케이션 추가¶

HarmonyOS 애플리케이션을 릴리스하는 경우에만 해당 RUM App ID를 추가합니다.

rum.setConfig({
    androidAppId: 'YOUR_ANDROID_APP_ID',
    iOSAppId: 'YOUR_IOS_APP_ID',
+    harmonyAppId: 'YOUR_HARMONY_APP_ID',
    // ...
});

각 플랫폼은 Guance에서 생성한 각자의 RUM App ID를 사용해야 합니다.

HarmonyOS에서 Action을 자동으로 수집해야 하는 경우, 애플리케이션 시작 단계에서 다음을 호출해야 합니다.

gcActionTracking.startTracking();

4. JS 수집기 필요 시 조정¶

0.2.6 이하 버전에서 업그레이드하고 Vue 3 사용 시¶

Vue 3에서는 createSSRApp()이 반환한 애플리케이션 인스턴스를 gcViewTracking.startTracking()에 전달해야 합니다.

-gcViewTracking.startTracking();

export function createApp() {
    const app = createSSRApp(App);
+    gcViewTracking.startTracking(app);
    return { app };
}

자세한 내용은 View 자동 수집을 참조하세요.

gcRequest에서 gcResourceTracking으로 마이그레이션¶

gcResourceTracking은 0.2.7부터 제공되며, 표준 uni.request를 가로채는 데 사용됩니다. 프로젝트에서 더 이상 사용되지 않는 gcRequest를 계속 사용 중인 경우, gcResourceTracking으로 마이그레이션하는 것을 권장합니다. 두 수집 방식을 동시에 활성화하지 마세요. 자세한 내용은 Resource 자동 수집을 참조하세요.

호스트 앱의 uni 미니 프로그램 마이그레이션¶

이 섹션에서 "uni 미니 프로그램"은 uni-app으로 개발하여 wgt 리소스 패키지로 제작하고 호스트 앱에서 실행하는 프로젝트를 특별히 지칭합니다.

0.3.0에서 App 네이티브 언어 플러그인의 사용 방식과 릴리스 위치가 변경되었습니다.

  # uni 미니 프로그램 프로젝트
- nativeplugins/GCUniPlugin
  uni_modules/GC-JSPlugin

  # 호스트 앱
- nativeplugins/GCUniPlugin에서 호스트 측 네이티브 의존성 가져오기
+ dist/unimp-host-extension에서 GC-UniPlugin 네이티브 의존성 라이브러리 가져오기

uni 미니 프로그램 프로젝트는 더 이상 App 네이티브 언어 플러그인이 필요하지 않으며, uni-app 애플리케이션에서 사용하는 GC-UniPlugin UTS 플러그인도 설치하지 않습니다. 호스트 앱은 계속 Native SDK를 통합하고, dist/unimp-host-extension에서 해당 플랫폼의 GC-UniPlugin 네이티브 의존성 라이브러리를 추가해야 합니다.

1. uni 미니 프로그램 프로젝트 조정¶

1. nativeplugins/GCUniPlugin 및 manifest.json에서 해당하는 App 네이티브 언어 플러그인 구성을 삭제합니다.
2. GC-JSPlugin 디렉터리 전체를 0.3.0 이상 버전으로 교체합니다.
3. GC-UniPlugin을 설치하지 않고, GC-UniPlugin/setup.js도 로드하지 않습니다.

조정 후 디렉터리 구조:

uni_modules/
└── GC-JSPlugin

여기서는 SDK 의존성만 조정하며, uni 미니 프로그램 엔지니어링을 업그레이드하거나 개조할 필요는 없습니다. 기존 코드에서 uni.requireNativePlugin()을 직접 호출하여 SDK 객체를 가져오는 경우, 다음 단계의 수정도 완료해야 합니다.

2. SDK API 임포트 방식 수정¶

App 네이티브 언어 플러그인을 제거한 후, uni.requireNativePlugin()을 직접 호출하면 네이티브 플러그인을 찾을 수 없다는 오류가 발생하거나 유효하지 않은 객체가 반환되어 이후 메서드를 호출할 수 없습니다. GC-JSPlugin에서 SDK API를 임포트하도록 변경합니다.

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-JSPlugin';

GC-JSPlugin은 호스트에 해당 네이티브 Module이 등록되어 있는지 확인합니다. Module을 사용할 수 없는 경우, 이후 API 호출은 안전하게 폴백(fallback)되어 비즈니스 코드가 중단되지 않도록 합니다. GC-UniPlugin 네이티브 의존성 라이브러리가 통합되지 않은 베이스에서 디버깅할 때, 콘솔에 "현재 실행 중인 베이스에 네이티브 플러그인이 포함되어 있지 않습니다. manifest에서 해당 플러그인을 구성해 주세요."와 같은 일반적인 메시지가 표시될 수 있습니다. 이 시나리오에서는 App 네이티브 언어 플러그인을 다시 구성할 필요가 없으며, 네이티브 기능은 의존성 통합이 완료된 호스트 앱에서 검증해야 합니다.

3. 호스트 앱 의존성 업데이트¶

호스트 앱은 계속 Native SDK를 통합합니다. 기존에 nativeplugins/GCUniPlugin에서 가져오던 호스트 측 네이티브 의존성을 dist/unimp-host-extension에서 해당 플랫폼의 GC-UniPlugin 네이티브 의존성 라이브러리로 교체합니다.

• Android: gc-uniplugin-<version>.aar
• iOS: GC-UniPlugin-App.xcframework
• HarmonyOS: GCUniPlugin.har

GC-UniPlugin 네이티브 의존성 라이브러리는 uni 미니 프로그램 실행 환경에 SDK Module을 등록하는 데 사용되며, 이전 버전의 App 네이티브 언어 플러그인이 제공했던 호스트 측 네이티브 기능에 해당합니다.

각 플랫폼의 의존성 및 등록 방식은 호스트 앱 통합을 참조하세요.

업그레이드 후 검증¶

업그레이드를 완료하고 커스텀 베이스 또는 설치 패키지를 다시 빌드한 후, 다음 항목을 확인하세요.

• 애플리케이션에서 Native SDK가 한 번만 초기화됩니다.
• 활성화된 RUM, Log 및 Trace 데이터가 정상적으로 보고됩니다.
• uni-app 애플리케이션에서 이전 네이티브 언어 플러그인이 삭제되었고, setup.js가 JS 수집기보다 먼저 로드됩니다.
• uni 미니 프로그램 호스트 앱이 wgt를 열기 전에 Native SDK 초기화 및 Module 등록을 완료합니다.
• uni.request의 비즈니스 콜백이 정상적으로 유지되며, Trace가 활성화된 경우 Trace Header가 정상적으로 추가됩니다.

Native API를 호출할 수 없는 경우 문제 해결을 참조하세요.