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 truewatch-cocos install --project ., then reopen Cocos Creator and enable the truewatch-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 truewatch-cocos install --project /absolute/path/to/cocos-project

Wrong Creator Entry Point¶

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

• Creator 2: @truewatchtech/cocos-sdk/creator2
• Creator 3: @truewatchtech/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.truewatch.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.

RUM Available but No View¶

• Enable autoTrack.scenes: true; or
• Call truewatchSdk.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.

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 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¶

truewatchSdk.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.