Cocos Creator 앱 연동¶

Cocos Creator SDK를 통해 Android 및 iOS 네이티브 게임의 RUM, Log, Trace, Session Replay 데이터를 수집합니다.

읽기 경로¶

• 최초 연동: 빠른 시작을 먼저 읽으세요.
• 설치 및 네이티브 빌드: 이 문서를 계속 읽으세요.
• 파라미터 설명: SDK 초기화, RUM 구성, Log 구성, Trace 구성 및 Cocos Creator 세션 리플레이(실험적)를 확인하세요.
• 수동 수집: RUM 수동 계측 및 Logger 로그 출력을 확인하세요.
• 수집 범위 및 개인정보 보호: 앱 데이터 수집 및 데이터 및 개인정보 보호를 확인하세요.
• 문제 해결: 문제 해결을 확인하세요.

지원 범위¶

Creator 3.0~3.6.2에서도 연동을 시도할 수 있지만, 안정적인 네이티브 빌드 확장 API는 3.6.3부터 제공됩니다.

SDK는 Android, iOS 네이티브 빌드에서만 Native SDK를 호출합니다. 브라우저 미리보기 및 Web 빌드에서는 데이터를 업로드하지 않습니다.

현재 SDK 버전 조합¶

이 Cocos 연동 문서에서는 다음 버전 조합을 사용합니다.

기본 패키지 @cloudcare/cocos-sdk와 옵션 패키지 @cloudcare/cocos-session-replay는 모두 0.1.0-alpha.6을 사용합니다. Replay 패키지는 기본 패키지와 완전히 동일한 버전을 요구합니다. 기본 패키지는 Replay에 의존하지 않습니다. 표의 Session Replay 네이티브 의존성은 Replay 통합을 활성화한 경우에만 추가됩니다.

Cocos 빌드 확장은 이에 대응하는 Android/iOS 네이티브 SDK 의존성을 구성합니다. Android Gradle Plugin은 아래 내용에 따라 연동해야 합니다. 네이티브 호스트 하이브리드 프로젝트도 이 버전 조합을 사용합니다.

사전 요구 사항¶

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

앱 연동¶

1. RUM > 앱 생성 > Android/iOS로 이동합니다.
2. Cocos Creator Android와 iOS용 앱을 각각 생성합니다.
3. 두 앱의 앱 ID를 기록하고, 이후 각각 androidAppId와 iosAppId에 입력합니다.

4. 앱 연동 방식을 선택합니다.

   • 공용 네트워크 DataWay: DataKit 수집기를 설치하지 않고 데이터를 직접 수신합니다.
   • 로컬 환경 배포: 사전 요구 사항을 충족한 후 로컬 DataKit이 데이터를 수신합니다.

설치¶

Creator 2와 Creator 3은 기본 npm 패키지를 공유합니다. RUM, Log, Trace만 연동하는 경우 Cocos 프로젝트 루트 디렉터리에서 실행합니다.

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-cocos install --project .

Session Replay가 필요하면 두 패키지를 함께 설치하고 네이티브 통합을 활성화합니다.

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
npx --no-install guance-cocos install --project . --replay

두 패키지의 임포트 진입점은 동일한 Creator 메이저 버전을 사용해야 하며, 코드에서 withSessionReplay()로 SDK를 조합해야 합니다. 자세한 내용은 세션 리플레이 초기화를 참고하세요. npm 패키지만 설치하면 네이티브 Replay 통합이 자동으로 활성화되지 않습니다.

Replay 설치 파라미터¶

다음 파라미터는 SDK를 연동하는 개발자가 프로젝트 설치 단계에서 사용하는 것으로, 런타임 초기화 파라미터가 아닙니다.

통합을 비활성화할 때는 다음을 실행합니다.

npx --no-install guance-cocos install --project . --no-replay

수정 후에는 네이티브 프로젝트를 다시 생성하고 컴파일해야 합니다. CocoaPods를 사용하는 경우 pod install도 실행해야 합니다. 기존 ReplayPrivacy.ts와 .meta는 유지되므로 씬 또는 프리팹 참조가 깨지지 않습니다. 네이티브 호스트가 자체적으로 사용하는 Replay 의존성은 계속 호스트가 관리합니다. npm 패키지만 제거하거나 JS 프레임 캡처를 중지해도 이미 링크된 네이티브 라이브러리는 제거되지 않습니다.

설치 관리자는 Cocos Creator 메이저 버전을 자동으로 인식합니다. 프로젝트 메타데이터에서 인식할 수 없는 경우 --creator 2 또는 --creator 3을 명시적으로 전달할 수 있습니다.

설치 관리자는 빌드 확장과 네이티브 Bridge를 다음 디렉터리에 복사합니다.

• Creator 3: extensions/guance-cocos-sdk
• Creator 2: packages/guance-cocos-sdk

--replay를 활성화하면 설치 관리자는 ReplayPrivacy 컴포넌트 스크립트를 assets/guance-cocos-sdk/ReplayPrivacy.ts에 복사하여 씬 또는 프리팹에서 Session Replay 노드 마스킹을 구성할 수 있게 합니다. 자세한 내용은 ReplayPrivacy 컴포넌트 사용을 참고하세요.

설치가 완료되면 Cocos Creator를 다시 열고 guance-cocos-sdk 확장이 활성화되었는지 확인한 후 Android 또는 iOS 네이티브 프로젝트를 다시 생성하세요. 설치 명령을 반복 실행하면 동일한 디렉터리가 업데이트됩니다.

TypeScript 코드는 Creator 메이저 버전에 따라 임포트 진입점을 선택해야 합니다. Creator 2는 @cloudcare/cocos-sdk/creator2를, Creator 3은 @cloudcare/cocos-sdk/creator3을 사용합니다.

네이티브 프로젝트 빌드¶

Android¶

빌드 확장은 네이티브 프로젝트를 생성한 후 다음 구성을 자동으로 수행합니다.

• Cocos Bridge 및 Android 네이티브 SDK 의존성을 추가합니다.
• AndroidX를 활성화합니다.
• compileSdkVersion 및 Build Tools의 최소 버전을 34로 올립니다.
• minSdkVersion의 최소 버전을 21로 올립니다.

기본 통합에는 ft-sdk와 ft-native가 추가됩니다. --replay를 활성화한 경우에만 Replay Bridge, ft-session-replay 및 필요한 AndroidX Fragment 의존성이 추가됩니다.

프로젝트에서 이미 더 높은 버전을 사용 중이면 확장이 기존 구성을 유지합니다. Cocos Creator 네이티브 빌드를 완료한 후 Android Studio 또는 명령줄을 사용하여 앱을 정상적으로 컴파일하면 됩니다.

iOS¶

기본적으로 CocoaPods를 사용합니다. 0.1.0-alpha.5부터는 프로젝트 구성에서 Swift Package Manager를 선택할 수도 있습니다.

CocoaPods(기본)¶

빌드 확장은 FTCocosBridge를 생성된 프로젝트의 Podfile에 추가합니다. iOS 프로젝트를 다시 생성할 때마다 Podfile이 있는 디렉터리로 이동하여 다음을 실행합니다.

pod install

그런 다음 생성된 .xcworkspace를 사용하여 앱을 컴파일하고, .xcodeproj는 사용하지 마세요. 기본 통합은 GuanceSDK/Agent에만 의존합니다. --replay를 활성화하면 확장이 로컬 FTCocosReplayBridge Pod를 추가하며, 이 Pod가 GuanceSDK/FTSessionReplay에 의존합니다. 두 모듈은 동일한 버전의 네이티브 SDK를 공유합니다.

Swift Package Manager(SPM)¶

Cocos 프로젝트 루트 디렉터리(assets와 같은 수준)에서 cocos-sdk.config.json을 생성하거나 수정합니다.

{
  "ios": {
    "dependencyManager": "spm"
  }
}

이 파일은 네이티브 빌드 시 의존성 설치 방식을 제어하며, TypeScript의 SDK 초기화 파라미터를 수정할 필요가 없습니다. 구성하지 않으면 cocoapods를 사용합니다.

확장 설치 시에도 동일한 구성을 저장할 수 있습니다.

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-cocos install --project . --ios-dependency-manager spm

구성을 수정한 후 Creator를 다시 열고 iOS 네이티브 프로젝트를 생성하세요. 빌드 확장은 로컬 FTCocosBridge Swift Package를 자동으로 연결하고 잠금 버전의 GuanceSDK를 해석합니다. --replay를 활성화하면 로컬 FTCocosReplayBridge Swift Package도 연결하고 동일한 버전의 GuanceSessionReplay를 해석합니다. 최초 해석 시 의존성 저장소에 접근할 수 있어야 합니다. 현재 잠긴 iOS SDK 버전은 1.6.8-alpha.5입니다.

새로운 SPM 프로젝트는 pod install을 실행할 필요 없이 생성된 .xcodeproj를 바로 열어 컴파일합니다. 네이티브 호스트가 여전히 CocoaPods로 다른 의존성을 관리한다면 호스트의 .xcworkspace를 계속 사용하세요.

CocoaPods에서 전환

• 확장은 자동으로 생성된 SDK Pod 구성 블록을 제거합니다. 이미 Pods가 설치된 경우 자동으로 pod install을 실행하여 통합을 업데이트하므로, 마이그레이션 시에도 로컬 환경에서 CocoaPods를 실행할 수 있어야 합니다.
• 수동으로 선언한 FTCocosBridge, FTCocosReplayBridge, GuanceSDK 또는 동일한 네이티브 SDK에 의존하는 다른 Pod는 먼저 마이그레이션을 완료해야 합니다. 설치 관리자는 충돌을 감지하면 오류를 보고하여 중복 링크를 방지합니다.
• 호스트의 다른 Pod 의존성은 기존 관리 방식을 유지합니다.
• CocoaPods로 다시 전환해야 한다면 ios.dependencyManager를 cocoapods로 변경하고 프로젝트를 다시 생성한 후 pod install을 실행합니다.

Creator 3가 Xcode 빌드 과정에서 CMake 재생성을 트리거하면 확장이 SPM 패키지 참조와 링크 구성을 자동으로 복원합니다. CMake 재생성만 별도로 실행한 경우 Creator의 네이티브 빌드 통합을 다시 실행한 다음 Xcode를 여세요.

SDK 업데이트¶

npm 패키지를 업그레이드한 후에는 설치 관리자를 다시 실행하고 네이티브 프로젝트를 다시 생성해야 합니다.

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6
npx --no-install guance-cocos install --project .

Replay를 사용하는 프로젝트는 두 npm 패키지를 함께 업그레이드해야 합니다.

npm install @cloudcare/cocos-sdk@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
npx --no-install guance-cocos install --project . --replay

0.1.0-alpha.5 또는 이전 통합 패키지에서 업그레이드하는 경우 Replay 임포트와 Camera 호출도 마이그레이션해야 합니다. 패키지 분리 마이그레이션을 참고하세요.

CocoaPods를 사용하는 iOS 프로젝트는 pod install을 다시 실행해야 합니다. SPM을 사용하는 프로젝트는 Xcode가 의존성을 다시 해석합니다. 설치 관리자를 다시 실행할 때 --ios-dependency-manager를 지정하지 않으면 기존 프로젝트 구성이 유지됩니다.

다음 단계¶

설치를 완료한 후 빠른 시작에 따라 SDK를 초기화하고 첫 번째 데이터를 확인하세요. 전체 구성 및 기능 범위에 대한 자세한 내용은 이 페이지 상단의 읽기 경로에서 해당 주제로 이동하여 확인하세요.