문제 해결¶

초기화 후 데이터 없음¶

순서대로 확인합니다:

반드시 Android 또는 iOS 네이티브 빌드를 사용해야 합니다. 브라우저 미리보기와 Web 빌드에서는 데이터가 전송되지 않습니다.
npx --no-install guance-cocos install --project .를 실행했는지 확인하고, Cocos Creator를 다시 열어 guance-cocos-sdk 확장을 활성화합니다.
npm 패키지를 업그레이드하거나 재설치한 후에는 반드시 네이티브 프로젝트를 다시 생성해야 합니다.
datakitUrl 또는 datawayUrl과 clientToken이 올바르게 설정되었는지 확인합니다.
Android에는 androidAppId를, iOS에는 iosAppId를 반드시 제공해야 합니다.
초기화 단계에서 debug: true를 설정하고 Cocos 및 네이티브 로그를 확인합니다.
sampleRate가 0이 아닌지 확인합니다.
로컬 환경에 배포한 경우 DataKit 무데이터 문제를 이어서 확인합니다.

설치기가 Cocos 프로젝트를 찾지 못함¶

다음과 같은 메시지가 표시되는 경우:

No Cocos project found ... (missing assets directory)

--project는 assets 디렉터리가 포함된 Cocos 프로젝트 루트 디렉터리를 가리켜야 합니다:

npx --no-install guance-cocos install --project /absolute/path/to/cocos-project

잘못된 Creator 진입점 사용¶

Creator 2와 Creator 3는 동일한 @cloudcare/cocos-sdk npm 패키지를 사용하지만 임포트 진입점이 다릅니다:

Creator 2: @cloudcare/cocos-sdk/creator2
Creator 3: @cloudcare/cocos-sdk/creator3

임포트 진입점을 수정한 후 설치기를 다시 실행하고 네이티브 프로젝트를 생성합니다. 설치기가 Creator 버전을 인식하지 못하면 --creator 2 또는 --creator 3을 명시적으로 전달합니다.

Android Bridge 또는 의존성 오류¶

ClassNotFoundException, FTCocosBridge를 찾을 수 없음 또는 네이티브 SDK 클래스 누락이 발생하는 경우:

생성된 프로젝트에 cocos-sdk-native/android가 포함되어 있는지 확인합니다.
앱 모듈의 build.gradle에 COCOS_SDK_BEGIN 마커 블록이 있는지 확인합니다.
Gradle이 https://mvnrepo.guance.com/repository/maven-releases에 접근할 수 있는지 확인합니다.
AndroidX가 활성화되어 있는지 확인합니다.
Compile SDK와 Build Tools가 34 이상, Min SDK가 21 이상인지 확인합니다.
설치기를 다시 실행하고 프로젝트를 다시 생성합니다. 기존 Native 프로젝트만 재사용하지 마십시오.

iOS Bridge 또는 CocoaPods 오류¶

다음 확인 사항은 CocoaPods를 사용하는 프로젝트에 적용됩니다:

생성된 프로젝트에 cocos-sdk-native/ios가 포함되어 있는지 확인합니다.
Podfile에 pod 'FTCocosBridge'가 있는지 확인합니다.
Podfile이 있는 디렉터리에서 pod install을 다시 실행합니다.
.xcodeproj가 아닌 .xcworkspace를 사용합니다.
Xcode Build Folder를 정리한 후 다시 빌드합니다.

Creator 2 프로젝트의 iOS 최소 버전은 12.0으로 올라갑니다. Xcode 15 호환 링크 파라미터는 빌드 확장이 생성 구성에 자동으로 기록합니다.

iOS SPM 설정 미적용 또는 빌드 실패¶

0.1.0-alpha.5 이상 버전의 SDK 패키지를 설치했는지 확인하고, 설치기를 다시 실행하여 Creator 확장을 업데이트합니다. 기능 가용성은 SPM 연동 설명을 참조합니다.
cocos-sdk.config.json이 Cocos 프로젝트 루트 디렉터리에 있고 ios.dependencyManager가 spm인지 확인한 후 iOS 프로젝트를 다시 생성합니다.
생성 디렉터리의 cocos-sdk-native/FTCocosBridge/Package.swift와 앱 타깃의 FTCocosBridge 패키지 의존성을 확인합니다. 최초 해석에 실패하면 Xcode가 매니페스트의 Git 리포지토리와 버전 태그에 접근할 수 있는지 확인합니다.
수동으로 선언한 SDK Pod 또는 다른 Pod가 여전히 동일한 네이티브 SDK에 의존한다는 안내가 표시되면 먼저 해당 의존성 마이그레이션을 완료합니다. 기존 Pods 업데이트가 실패하면 로컬 pod 명령과 오류 메시지를 확인한 후 다시 시도합니다.
Creator 3에서 레거시 빌드 위치가 Packages를 지원하지 않는다는 안내가 표시되거나 CMake 재생성 후 패키지 참조가 사라진 경우, 업데이트된 Creator 빌드 확장을 다시 실행합니다. 확장은 빌드 위치 설정을 조정하고, Xcode에서 CMake 재생성이 트리거된 후 SPM 통합을 복원합니다.
새 SPM 프로젝트는 .xcodeproj를 엽니다. 호스트에 다른 Pods가 있으면 계속 .xcworkspace를 사용합니다. 링크 오류를 해결하기 위해 Bridge 또는 네이티브 SDK를 수동으로 중복 추가하지 마십시오.

RUM은 있는데 View가 없음¶

autoTrack.scenes: true를 활성화하거나
비즈니스 씬 진입 시 guanceSdk.rum.startView()를 호출하고, 이탈 시 stopView()를 호출합니다.

초기화 시점이 첫 번째 씬 시작보다 늦으면 씬 이벤트를 놓칠 수 있습니다. 첫 번째 수집 씬 이전에 초기화해야 합니다.

자동 Action 또는 Error가 동작하지 않음¶

Action:

autoTrack.actions: true인지 확인합니다.
인터랙션이 최종적으로 전역 TOUCH_END를 트리거하는지 확인합니다.
커스텀 입력 시스템 또는 전역 이벤트를 소비하는 컴포넌트는 Action API를 수동으로 호출해야 합니다.

Error:

autoTrack.errors: true인지 확인합니다.
현재 런타임에 전역 addEventListener가 제공되어야 합니다.
비즈니스에서 try/catch로 이미 처리된 예외는 addError()를 수동으로 호출해야 합니다.

Log 데이터 없음 또는 RUM 미연동¶

logger를 초기화하고 enableCustomLog: true를 설정합니다.
sampleRate와 logLevelFilters를 확인합니다.
Console 수집에는 autoTrack.console: true도 필요합니다.
RUM 연동에는 enableLinkRumData: true, 유효한 RUM 세션 및 현재 View가 필요합니다.
첫 번째 View보다 먼저 생성된 로그는 View에 연결되지 않을 수 있습니다.

Trace 헤더가 비어 있음¶

trace가 초기화되었는지 확인합니다.
URL은 비어 있지 않아야 하며 Native SDK가 처리할 수 있는 유효한 URL이어야 합니다.
Trace 샘플링 비율을 확인합니다.
지원되지 않는 플랫폼에서는 빈 객체를 반환합니다.
자동 주입은 런타임에서 제공하는 fetch와 XMLHttpRequest에만 적용됩니다.

네트워크 데이터 중복¶

다음 항목이 동시에 활성화되어 있는지 확인합니다:

autoTrack.network와 enableNativeUserResource
autoTrack.network와 enableNativeAutoTrace
자동 네트워크 수집과 비즈니스 수동 Resource/Trace

동일한 요청 스택에 대해 수집 경로를 하나만 유지한 후 RUM Resource 수와 요청 헤더를 비교합니다.

Android는 JS 네트워크 수집을 유지하고 네이티브 setEnableHttpURLConnectionResource(false)를 유지하는 것이 권장됩니다. enableNativeUserResource는 전체 스위치이며 HttpURLConnection 수집을 단독으로 활성화하지 않습니다. Android 네트워크 수집 권장 사항을 참조합니다.

iOS는 Creator 2의 NSURLConnection과 Creator 3.8.8의 NSURLSession을 구분해야 합니다. 전자는 iOS SDK 1.6.8-alpha.5부터 별도 스위치를 통해 활성화되고, 후자는 기존 스위치로 제어됩니다. 어느 경로든 JS 자동 또는 수동 Resource와 동시에 수집하면 중복될 수 있습니다. iOS 네트워크 수집 권장 사항을 참조합니다.

Replay 패키지 또는 네이티브 통합 누락¶

0.1.0-alpha.6부터 Replay에는 별도 npm 패키지, 코드 결합, 네이티브 통합의 세 단계가 필요합니다:

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

그런 다음 네이티브 프로젝트를 다시 생성하고 컴파일합니다. CocoaPods를 사용하는 경우 pod install을 실행합니다. 코드는 withSessionReplay(baseSdk)가 반환하는 인스턴스를 사용합니다. 패키지 분리 마이그레이션을 참조합니다.

안내 메시지 또는 증상	처리 방법
`Cannot find module '@cloudcare/cocos-session-replay/...'` / `Session Replay is not installed`	현재 Cocos 프로젝트에 기본 패키지와 완전히 동일한 버전의 Replay 패키지를 설치합니다.
`Session Replay requires @cloudcare/cocos-session-replay`	기본 인스턴스를 초기화하기 전에 `withSessionReplay()`를 호출하고, `replay` 구성을 결합된 인스턴스에 전달합니다.
`SDK extension version or Creator engine does not match the base SDK`	두 패키지 버전이 완전히 동일한지 확인하고, 임포트 진입점이 모두 `/creator2` 또는 모두 `/creator3`인지 확인합니다.
`Install SDK extensions before start() or attach()`	결합 호출을 SDK 시작 또는 Hybrid 바인딩보다 먼저 수행합니다.
`Session Replay native integration is unavailable`	설치기 `--replay`를 실행하고 다시 빌드합니다. Hybrid 프로젝트는 네이티브 호스트가 호환 버전의 SDK를 초기화했는지도 확인해야 합니다.
기본 패키지가 더 이상 `setReplayCamera`를 내보내지 않음	결합된 인스턴스의 `guanceSdk.setReplayCamera(camera)`를 사용합니다.

설치기는 로컬에서 수정된 SDK 파일을 감지하면 중지하고 구체적인 경로를 안내합니다. 먼저 이러한 커스텀 수정 사항을 백업하고 확인한 후 다시 설치하십시오. 씬에서 참조하는 ReplayPrivacy.ts 또는 .meta를 직접 삭제하지 마십시오.

Session Replay 화면 없음¶

RUM이 초기화되었고 현재 유효한 View가 있는지 확인합니다.
씬에 Camera가 있는지 확인하거나 guanceSdk.setReplayCamera()를 호출합니다.
Replay와 RUM의 샘플링 비율이 0이 아닌지 확인합니다.
정지된 화면은 중복 프레임으로 판정되어 건너뜁니다.
콘솔에 캡처 중지 오류가 표시되는지 확인합니다.
SDK 버전 및 의존성 요구 사항에 따라 Session Replay 네이티브 의존성을 확인하고, 네이티브 프로젝트를 다시 생성하고 컴파일합니다.

Creator 3 Replay 화면 또는 터치 이상¶

0.1.0-alpha.7에서는 표시 Camera가 프레임 캡처의 영향을 받는 문제, UI 컨트롤이 소비한 터치가 Replay에서 누락되는 문제, Replay 수집이 정상 입력 분배에 영향을 주는 문제가 수정되었습니다. 업그레이드 절차에 따라 두 npm 패키지를 업데이트하고 다시 빌드합니다.

결합된 guanceSdk.setReplayCamera(camera)로 필요한 Camera를 지정했는지 확인합니다. SDK는 Camera 하나만 수집하며 여러 Camera 화면을 합성하지 않습니다.
Replay에 터치 위치가 없는 경우 touchPrivacy가 명시적으로 show로 설정되어 있는지 확인합니다. 기본값 hide에서는 위치를 기록하지 않습니다. autoTrack.actions와 Replay 터치 수집은 서로 독립적입니다.
버튼, 조이스틱, 빈 영역에서 각각 비즈니스 응답과 Replay 기록을 검증합니다. 이전 버전의 터치 누락을 보완하기 위해 비즈니스 입력 로직을 중복 호출하지 마십시오.
이미지를 축소한 후 터치와 마스크가 표시 좌표와 일치하는지 확인합니다. 인코딩된 이미지 크기를 게임 표시 크기로 직접 간주하지 마십시오.

초기화 파라미터 예외 발생¶

오류	원인
`Configure datakitUrl or datawayUrl with clientToken`	유효한 전송 주소가 설정되지 않음
`... must be between 0 and 1`	RUM, Log, Trace 또는 Replay 샘플링 비율이 범위를 벗어남
`captureFps must be an integer between 1 and 5`	Replay FPS가 `1–5` 범위의 정수가 아님
`maxImageDimension must be between 1 and 2048`	Replay 최장 변 길이가 범위를 벗어남
`... must not be empty`	View, Action, Resource Key 또는 Trace URL 등 필수 문자열이 비어 있음

성능 문제¶

Session Replay는 captureFps: 1, maxImageDimension: 720부터 시작합니다.
필요하지 않으면 Console 자동 수집을 끕니다.
로그 및 이벤트 속성에 대형 객체를 전달하지 마십시오.
필요한 Native 모니터링 지표만 활성화합니다.
네트워크 수집 중복 여부를 확인합니다.

SDK 종료 후 데이터 미수집¶

guanceSdk.shutdown()은 자동 리스너를 제거하고 Session Replay를 중지하며 Native SDK를 종료합니다. 종료 후에는 수집 메서드를 계속 호출하지 마십시오. 다시 활성화해야 하는 경우 앱을 재시작하고 초기화를 한 번 수행하는 것이 좋습니다.