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 SDK 버전은 실제로 설치된 npm 패키지를 기준으로 하며, 함께 제공되는 Android/iOS 네이티브 SDK 버전은 해당 npm 패키지의 의존성 구성에 따라 결정됩니다. Android Gradle Plugin은 별도로 연동해야 하며, 아래 표의 최소 버전 요구 사항을 충족해야 합니다.

기본 패키지 @cloudcare/cocos-sdk와 선택적 패키지 @cloudcare/cocos-session-replay는 완전히 동일한 버전을 사용해야 합니다. 기본 패키지는 Replay에 의존하지 않습니다. 표의 Session Replay 네이티브 의존성은 Replay 연동을 활성화한 경우에만 추가됩니다.

0.1.0-alpha.7에는 Replay 단일 프레임 크기 정책, Creator 3 카메라 및 터치 수집 수정 사항이 포함되어 있습니다. 업그레이드 시 두 패키지를 동시에 업그레이드하고 설치 프로그램을 다시 실행한 후 네이티브 프로젝트를 다시 빌드해야 합니다. 자세한 내용은 alpha.7로 업그레이드를 참조합니다.

Cocos 빌드 확장은 함께 제공되는 Android/iOS 네이티브 SDK 의존성을 구성합니다. Android Gradle Plugin은 아래 내용에 따라 연동해야 합니다. 네이티브 호스트 Hybrid 프로젝트도 설치된 npm 패키지에 맞는 네이티브 SDK 버전을 사용해야 합니다.

사전 조건¶

• 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
npx --no-install guance-cocos install --project .

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

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

기본 패키지와 Replay 패키지의 버전 번호는 완전히 동일해야 하며, Import 진입점도 동일한 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 메이저 버전에 따라 Import 진입점을 선택해야 합니다. Creator 2에서는 @cloudcare/cocos-sdk/creator2를, Creator 3에서는 @cloudcare/cocos-sdk/creator3를 사용합니다.

네이티브 프로젝트 빌드¶

Android¶

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

• Cocoa 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
npx --no-install guance-cocos install --project . --ios-dependency-manager spm

구성을 변경한 후 Creator를 다시 열고 iOS 네이티브 프로젝트를 생성합니다. 빌드 확장은 로컬 FTCocosBridge Swift Package를 자동으로 연결하고 고정 버전의 GuanceSDK를 해석합니다. --replay를 활성화하면 로컬 FTCocosReplayBridge Swift Package도 연결하고 동일한 버전의 네이티브 Replay 라이브러리를 해석합니다. 최초 해석 시 의존성 저장소에 액세스할 수 있어야 합니다. SPM 연동에는 iOS SDK가 1.6.8-alpha.5 이상이어야 하며, 구체적인 버전은 설치된 Cocos SDK npm 패키지에 따라 결정됩니다.

완전히 새로운 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
npx --no-install guance-cocos install --project .

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

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

0.1.0-alpha.5 또는 이전 통합 패키지에서 업그레이드하는 경우 Replay Import 및 Camera 호출도 마이그레이션해야 합니다. 패키지 분리 마이그레이션을 참조합니다.

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

다음 단계¶

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