문제 해결¶

초기화 후 데이터 없음¶

다음 순서로 확인하세요:

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 패키지를 사용하지만 import 진입점이 다릅니다:

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

import 진입점을 수정한 후 설치 프로그램을 다시 실행하고 네이티브 프로젝트를 생성하세요. 설치 프로그램이 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을 다시 실행하세요.
.xcworkspace를 사용하고 .xcodeproj는 사용하지 마세요.
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 Session 및 현재 View가 필요합니다.
첫 번째 View 이전에 생성된 로그에는 View가 연결되지 않을 수 있습니다.

Trace Header가 비어 있는 경우¶

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@0.1.0-alpha.6 @cloudcare/cocos-session-replay@0.1.0-alpha.6
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`	두 패키지 버전이 완전히 동일한지, import 진입점이 모두 `/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 네이티브 의존성을 확인하고 네이티브 프로젝트를 다시 생성하고 컴파일하세요.

초기화 매개변수 예외 발생¶

오류	원인
`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를 종료합니다. 종료 후에는 수집 메서드를 계속 호출하지 마세요. 다시 활성화해야 하는 경우 애플리케이션을 재시작하고 초기화를 한 번 완료하는 것이 좋습니다.