Data and Privacy¶

This document describes the sensitive data boundaries that the Cocos Creator SDK may involve in RUM, Log, Trace, and Session Replay.

Basic Principles¶

Only collect the data required to locate performance and stability issues.
Do not collect sensitive information such as passwords, verification codes, tokens, full ID card numbers, or bank card numbers.
After enabling auto-collection in a test environment, first inspect the actual reported content before deciding on production configuration.
Custom tags, logs, and manual Resource Body are the responsibility of the business for sanitization.

Session Replay¶

Default Rules¶

All EditBox nodes use mask by default.
Duplicate frames and frames currently being processed are skipped.
Frame masks are applied to node rectangles before entering the Native Bridge.

Using the ReplayPrivacy Component¶

For sensitive nodes in a scene or prefab, prioritize using the ReplayPrivacy component to configure masks. Both Creator 2 and Creator 3 support this component.

After installing the SDK, re-run the project installer in the Cocos project root directory:
```
npx --no-install truewatch-cocos install --project .
```
The installer copies the component script to assets/truewatch-cocos-sdk/ReplayPrivacy.ts according to the Creator major version. Reopen Cocos Creator, select Session Replay > ReplayPrivacy in the component menu of the target node, or drag the script into the Inspector.
Set Mode to Mask (default, gray mask) or Hide (black mask), and save the scene or prefab.

The component only affects Session Replay frame capture and does not change how the node is rendered in the live application. The SDK identifies valid and enabled components in the current scene at each frame capture, including prefabs instantiated at runtime. Once the component is disabled or removed, its rules no longer apply; code rules on the node and the EditBox default rule remain.

Keep the ReplayPrivacy class name and its .meta file to avoid breaking component references in scenes or prefabs. On Creator 3, the target UI node must have a UITransform to provide the mask bounds.

Adding Rules with Code¶

For nodes where adding a component is inconvenient, or for scenarios that require dynamic overrides, use setPrivacy():

truewatchSdk.replay.setPrivacy(passwordPanel, 'hide'); // black mask
truewatchSdk.replay.setPrivacy(playerName, 'mask'); // gray mask
truewatchSdk.replay.setPrivacy(playerName, 'unmask'); // clear code override

Rule priority on the same node is: setPrivacy() code rule > ReplayPrivacy component rule > EditBox default mask.

unmask only clears previously set code rules and then restores the component rule or the EditBox default rule. It never forces sensitive content to be displayed. For example, after a node component is set to Hide, calling setPrivacy(node, 'mask') changes it to a gray mask, and calling setPrivacy(node, 'unmask') restores the black mask. The component's Mode therefore only offers Mask and Hide.

When managing masks for different pages with code, set them when entering the page, clear them with unmask before leaving or destroying, and restore them on re-entry. Hiding a page alone does not remove registered code rules. See Managing masks by page for a complete example.

maskInputs does not control the EditBox default mask; setting it to false does not cancel this rule.

Mask Scope and Verification¶

The mask is based on the node's world-coordinate bounding box, projected by the capture Camera into a rectangular area in the screenshot. If you only need to mask a specific sensitive control, add the component to that control and align the node bounds with the target area.

For example, place three sensitive controls side by side on the same page, keeping public text or borders between and around the controls:

Target control	Configuration	Expected replay result
Player nickname	Add `ReplayPrivacy`, Mode set to Mask	Target rectangular area is displayed in gray
Account information	Add `ReplayPrivacy`, Mode set to Hide	Target rectangular area is displayed in black
Dynamic sensitive content	Call `setPrivacy(node, 'mask')`	Target rectangular area is displayed in gray
Public text and borders outside the rectangular area	Set no privacy rule	Remain visible and are not covered by adjacent control masks

After moving or scaling the control or its parent node, and after adjusting the Camera and screen adaptation mode, verify the replay results in the native runtime environments of Android and iOS: the mask should follow the target position, fully cover the sensitive content, and not extend to other controls outside the target rectangle. Rectangle edges are rounded to frame-capture pixels, so also check the edges for content leakage or unintended occlusion.

Mask Boundaries

The mask covers a rectangular area in the screenshot; child nodes and other overlapping content within the rectangle are also occluded. A child node's unmask cannot cancel pixels already covered by the parent node. Therefore, do not select an entire page container when only partial masking is needed.

Shader, particles, RenderTexture, custom drawing, content outside the bounding box, and other Camera views are not necessarily covered. Check the replay results scene by scene on a real device.

Network Data¶

Enabling autoTrack.network collects URLs, request headers, response headers, HTTP methods, and status codes.

Points to check carefully:

Account, token, or business ID in URL Query;
Authorization, Cookie, and custom authentication request headers;
User or tenant information in response headers.

The current Cocos API does not provide URL or Header filtering callbacks. If the network protocol contains sensitive fields, disable automatic network collection and use the manual Resource and Trace APIs only for allowed requests.

Automatic network collection does not read the request body or response body. The responseBody passed manually to addResource() is processed as provided by the business; it should be left unset by default, and sanitized and truncated first when troubleshooting requires it.

Log and Console¶

autoTrack.console converts Console arguments to text, which may include:

Debug tokens;
Complete API objects;
User input;
Account and device identifiers;
Business data in exception objects.

For production environments, keep console: false and report filtered content with truewatchSdk.logger.log().

Do not put sensitive objects directly into log attributes. Objects are JSON-serialized and then become part of the log data.

Error¶

Error Message and Stack may contain:

URLs;
File paths;
User input;
String results of business objects.

Clean sensitive values from the message, stack, and attributes before calling addError() manually. Automatic error listeners cannot provide sanitization callbacks; if exception content is not controllable, you can disable autoTrack.errors and report manually after sanitizing in the business error boundary.

User and Custom Tags¶

For userId, use an internal irreversible identifier; do not use a phone number or email as the ID.
Pass userEmail only when the business actually requires it.
Add only low-sensitivity, stable, filterable tags to extra and all globalContext.
Do not set high-cardinality fields or content that changes with every request as global tags.

Trace Header¶

Trace Headers should only be injected into trusted business domains. Third-party domains may receive trace identifiers, potentially exposing internal tracing relationships. When automatic network tracing cannot filter by domain, use trace.getHeaders() to manually control the injection scope.

Pre-release Checklist¶

Cover sensitive scenarios such as login, payment, chat, and account settings on a real device.
Check the URLs and Headers of RUM Resources.
Check Error Message, Stack, and custom attributes.
Check Console and custom logs.
Replay Session Replay to confirm that input fields and custom sensitive areas are masked.
Check that Trace Headers are only sent to allowed domains.