Troubleshooting¶

No Data After Initialization¶

Check the following in order:

1. You must use a native Android or iOS build. Browser preview and web builds do not report data.
2. Confirm you have run npx --no-install guance-cocos install --project ., then reopen Cocos Creator and enable the guance-cocos-sdk extension.
3. After upgrading or reinstalling the npm package, you must regenerate the native project.
4. Confirm that datakitUrl, or datawayUrl together with clientToken, is configured correctly.
5. Android must provide androidAppId, and iOS must provide iosAppId.
6. Set debug: true during initialization and check Cocos and native logs.
7. Confirm that sampleRate is not 0.
8. If you are using a local deployment, continue troubleshooting with DataKit No Data Issue.

Installer Cannot Find the Cocos Project¶

If you see:

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

--project must point to the root directory of a Cocos project that contains the assets directory:

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

Wrong Creator Entry Point¶

Creator 2 and Creator 3 use the same @cloudcare/cocos-sdk npm package, but their import entry points differ:

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

After changing the import entry point, rerun the installer and regenerate the native project. If the installer cannot identify the Creator version, pass --creator 2 or --creator 3 explicitly.

Android Bridge or Dependency Errors¶

When ClassNotFoundException occurs, FTCocosBridge cannot be found, or native SDK classes are missing:

1. Confirm the generated project contains cocos-sdk-native/android.
2. Check whether the app module's build.gradle contains the COCOS_SDK_BEGIN marker block.
3. Confirm Gradle can access https://mvnrepo.guance.com/repository/maven-releases.
4. Confirm AndroidX is enabled.
5. Confirm the Compile SDK and Build Tools are at least 34, and the Min SDK is at least 21.
6. Rerun the installer and regenerate the project. Do not reuse the old native project.

iOS Bridge or CocoaPods Errors¶

The following checks apply to projects that use CocoaPods:

1. Confirm the generated project contains cocos-sdk-native/ios.
2. Confirm that pod 'FTCocosBridge' exists in the Podfile.
3. Run pod install again in the directory containing the Podfile.
4. Use .xcworkspace, not .xcodeproj.
5. Clean the Xcode Build Folder and rebuild.

For Creator 2 projects, the minimum iOS version is raised to 12.0. Xcode 15-compatible linker flags are automatically written into the generated configuration by the build extension.

iOS SPM Configuration Is Not Applied or the Build Fails¶

1. Confirm you have installed SDK package 0.1.0-alpha.5 or later, and rerun the installer to update the Creator extension. For feature availability, see SPM Integration Guide.
2. Confirm that cocos-sdk.config.json is located in the Cocos project root and that ios.dependencyManager is spm, then regenerate the iOS project.
3. Check cocos-sdk-native/FTCocosBridge/Package.swift in the generated directory, as well as the FTCocosBridge package dependency of the app target. If the first resolution fails, confirm that Xcode can access the Git repositories and version tags in the manifest.
4. If you are prompted that a manually declared SDK Pod or another Pod still depends on the same native SDK, migrate these dependencies first. If updating existing Pods fails, check the local pod command and the error message, then retry.
5. If Creator 3 reports that legacy build locations do not support Packages, or package references are lost after CMake regeneration, rerun the updated Creator build extension. The extension adjusts the build location settings and restores SPM integration after Xcode triggers CMake regeneration.
6. For a new SPM-only project, open .xcodeproj; if the host has other Pods, continue using .xcworkspace. Do not manually add a second Bridge or native SDK to resolve linker errors.

RUM Available but No View¶

• Enable autoTrack.scenes: true; or
• Call guanceSdk.rum.startView() when entering a business scene, and call stopView() when leaving it.

If initialization happens after the first scene has started, scene events may be missed. Initialize before the first scene to be tracked.

Automatic Actions or Errors Do Not Take Effect¶

Action:

• Confirm autoTrack.actions: true;
• Confirm that the interaction ultimately triggers the global TOUCH_END;
• Custom input systems or components that swallow global events must call the Action API manually.

Error:

• Confirm autoTrack.errors: true;
• The current runtime must provide a global addEventListener;
• Exceptions already caught by business try/catch code must call addError() manually.

Log Has No Data or No RUM Association¶

• Initialize logger and set enableCustomLog: true.
• Check sampleRate and logLevelFilters.
• Console collection also requires autoTrack.console: true.
• RUM association requires enableLinkRumData: true, a valid RUM Session, and a current View.
• Logs produced before the first View may not be associated with a View.

Trace Header Is Empty¶

• Confirm that trace is initialized.
• The URL must not be empty and must be a valid URL that the native SDK can handle.
• Check the Trace sample rate.
• Unsupported platforms return an empty object.
• Automatic injection only covers the fetch and XMLHttpRequest provided by the runtime.

Duplicate Network Data¶

Check whether any of the following are enabled at the same time:

• autoTrack.network and enableNativeUserResource;
• autoTrack.network and enableNativeAutoTrace;
• Automatic network collection and manual business Resource/Trace.

Keep only one collection path for the same request stack, then compare the RUM Resource count with the request headers.

For Android, it is recommended to keep JS network collection and leave native setEnableHttpURLConnectionResource(false) unchanged. enableNativeUserResource is the master switch and does not enable HttpURLConnection collection on its own. See Android Network Collection Recommendations.

For iOS, distinguish between NSURLConnection in Creator 2 and NSURLSession in Creator 3.8.8. The former is enabled through a separate switch starting with iOS SDK 1.6.8-alpha.5, while the latter is controlled by the existing switch. If either path is collected together with JS automatic or manual Resources, duplication may occur. See iOS Network Collection Recommendations.

Missing Replay Package or Native Integration¶

Starting with 0.1.0-alpha.6, Replay requires three steps: a separate npm package, code composition, and native integration:

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

Then regenerate and compile the native project; run pod install if you use CocoaPods. Use the instance returned by withSessionReplay(baseSdk). See Package Migration.

When the installer detects locally modified SDK files, it stops and reports the specific paths. Back up and review these custom modifications before reinstalling. Do not directly delete ReplayPrivacy.ts or .meta referenced by scenes.

Session Replay Has No Frames¶

1. Confirm that RUM is initialized and a valid View currently exists.
2. Confirm that there is a Camera in the scene, or call guanceSdk.setReplayCamera().
3. Confirm that the Replay and RUM sample rates are not 0.
4. Static frames are treated as duplicate frames and are skipped.
5. Check the console for capture-stop errors.
6. Check the Session Replay native dependencies against the current SDK version combinations, then regenerate and compile the native project.

Initialization Parameters Throw Exceptions¶

Performance Issues¶

• Start Session Replay with captureFps: 1 and maxImageDimension: 720.
• Disable automatic Console collection when it is not needed.
• Avoid passing large objects in logs and event attributes.
• Enable only the native monitoring metrics you need.
• Check for duplicate network collection.

No Collection After Shutting Down the SDK¶

guanceSdk.shutdown() removes automatic listeners, stops Session Replay, and shuts down the native SDK. Do not continue calling collection methods after shutdown. If you need to re-enable the SDK, restart the application and complete initialization.