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 that npx --no-install truewatch-cocos install --project . has been executed. Reopen Cocos Creator and enable the truewatch-cocos-sdk extension.
3. After upgrading or reinstalling the npm package, regenerate the native project.
4. Confirm that datakitUrl, or datawayUrl together with clientToken, is correctly configured.
5. Android requires androidAppId, and iOS requires iosAppId.
6. Set debug: true during initialization and check the Cocos and native logs.
7. Confirm that sampleRate is not 0.
8. If deploying in a local environment, continue troubleshooting with DataKit No Data Issues.

Installer Reports Cocos Project Not Found¶

If the following appears:

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 truewatch-cocos install --project /absolute/path/to/cocos-project

Wrong Creator Entry Used¶

Creator 2 and Creator 3 share the same @truewatchtech/cocos-sdk npm package, but they have different import entries:

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

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

Android Bridge or Dependency Errors¶

When you encounter ClassNotFoundException, FTCocosBridge not found, or missing native SDK classes:

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

iOS Bridge or CocoaPods Errors¶

The following checks apply to projects using 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.

The minimum iOS version of Creator 2 projects is raised to 12.0. Xcode 15-compatible linker parameters are automatically written to the generated configuration by the build extension.

iOS SPM Configuration Not Applied or Build Fails¶

1. Confirm that a SDK package version of 0.1.0-alpha.5 or later is installed, and rerun the installer to update the Creator extension. For feature availability, see SPM Integration.
2. Confirm that cocos-sdk.config.json is located in the Cocos project root directory and ios.dependencyManager is set to spm; then regenerate the iOS project.
3. Check cocos-sdk-native/FTCocosBridge/Package.swift in the generated directory and the FTCocosBridge package dependency of the app target. If the first resolution fails, confirm Xcode can access the Git repository and version tags in the manifest.
4. If the prompt indicates that a manually declared SDK Pod or other Pods still depend on the same native SDK, complete the migration of these dependencies first. If updating the existing Pods fails, check the local pod command and error messages, then retry.
5. In Creator 3, if it 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 fresh SPM project, open .xcodeproj. If the host has other Pods, continue using .xcworkspace. Do not manually add a second Bridge or native SDK to resolve link errors.

Has RUM but No View¶

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

If initialization happens after the first scene starts, scene events may be missed. Initialize before the first scene to be collected.

Automatic Action or Error Not Working¶

Action:

• Confirm autoTrack.actions: true;
• Confirm the interaction ultimately triggers the global TOUCH_END;
• Custom input systems or components that consume global events need to 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 need to call addError() manually.

Log Has No Data or No RUM Association¶

• Initialize the 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 generated before the first View may not have a View association.

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 fetch and XMLHttpRequest provided by the runtime.

Duplicate Network Data¶

Check whether the following are enabled at the same time:

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

Keep only one collection path for the same request stack, then compare the number of RUM Resources with the request headers.

Missing Replay Package or Native Integration¶

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

npm install @truewatchtech/cocos-sdk @truewatchtech/cocos-session-replay
npx --no-install truewatch-cocos install --project . --replay

Then regenerate and compile the native project. If using CocoaPods, run pod install. In code, use the instance returned by withSessionReplay(baseSdk). See Package Migration.

The installer stops and reports the specific path when it detects locally modified SDK files. Back up and review these custom modifications before reinstalling. Do not simply delete ReplayPrivacy.ts or its .meta referenced in the scene.

Session Replay Shows No Frames¶

1. Confirm RUM is initialized and a valid View currently exists.
2. Confirm a Camera exists in the scene, or call truewatchSdk.setReplayCamera().
3. Confirm neither the Replay nor RUM sample rate is 0.
4. Static frames are identified as duplicate frames and skipped.
5. Check the console for capture stop errors.
6. Check the Session Replay native dependencies against the SDK Version and Dependency Requirements, then regenerate and compile the native project.

Creator 3 Replay Frames or Touch Abnormalities¶

0.1.0-alpha.7 fixes issues where the display Camera was affected by frame capture, touches consumed by UI controls were missing in Replay, and Replay collection affected normal input distribution. Update both npm packages following the Upgrade Steps and rebuild.

• Confirm that the combined truewatchSdk.setReplayCamera(camera) is used to specify the desired Camera. The SDK captures only one Camera and does not composite frames from multiple Cameras.
• If Replay has no touch positions, check whether touchPrivacy is explicitly set to show. The default hide does not record positions. autoTrack.actions and Replay touch capture are independent.
• Verify business responses and Replay recordings for buttons, joysticks, and empty areas separately. Avoid calling business input logic repeatedly to compensate for touch omissions in the older version.
• After images are scaled down, verify that touches and masks align with display coordinates. Do not treat the encoded image dimensions as the game display dimensions.

Initialization Parameters Throw Exceptions¶

Performance Issues¶

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

No Data Collection After Shutting Down the SDK¶

truewatchSdk.shutdown() removes automatic listeners, stops Session Replay, and shuts down the native SDK. Do not continue calling collection methods after shutdown. To re-enable, restart the application and complete one initialization.