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 data needed to pinpoint performance and stability issues.
• Do not collect sensitive information such as passwords, verification codes, tokens, full identity document numbers, or bank card numbers.
• After enabling automatic collection in a test environment, first review the content actually reported, then decide on the production configuration.
• The business is responsible for sanitizing custom tags, logs, and manual Resource bodies.

Session Replay¶

Default Rules¶

• All EditBox nodes use mask by default.
• Duplicate frames and frames being processed are skipped.
• Node rectangular masks are applied to captured frames before they enter the Native Bridge.

Using the ReplayPrivacy Component¶

For sensitive nodes in scenes or prefabs, prefer using the ReplayPrivacy component to configure masks. Both Creator 2 and Creator 3 support this component.

1. After installing the SDK, re-run the project installer in the Cocos project root directory:

   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
   

2. The installer copies the component script to assets/guance-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.

3. Set Mode to Mask (default, gray mask) or Hide (black mask), then save the scene or prefab.

The component only affects Session Replay frame captures and does not change the nodes displayed in real time in the application. The SDK identifies valid and enabled components in the current scene at each frame capture, including prefabs instantiated at runtime. After the component is disabled or removed, its rules no longer take effect; code rules on nodes and the EditBox default rules remain.

Keep the ReplayPrivacy class name and the .meta file of the script to avoid breaking component references in scenes or prefabs. In Creator 3, the target UI node needs to have a UITransform to provide the mask boundary.

Adding Rules with Code¶

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

The guanceSdk below refers to the instance obtained by composing with withSessionReplay(). The base package itself does not provide .replay.

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

For the same node, the rule priority is: setPrivacy() code rules > ReplayPrivacy component rules > EditBox default mask.

unmask only clears previously set code rules and then restores the component rules or the EditBox default rules. It does not force 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') again restores the black mask. Therefore, the component's Mode only provides Mask and Hide.

When using code to manage masks for different pages, set the rules when entering the page, clear them with unmask before leaving or destroying the page, and restore them when re-entering. Merely hiding a page does not delete registered code rules. See Managing Masks per Page for a complete example.

The current Replay configuration does not provide a maskInputs switch, so the EditBox default mask cannot be turned off through this field.

Mask Coverage and Verification¶

The mask is based on the node's world-coordinate bounding box and is projected through the frame capture Camera onto a rectangular area in the screenshot. If you only need to cover a certain sensitive control, add the component to that control and keep the node boundary aligned with the target area.

For example, when three sensitive controls are placed side by side on the same page, keep public text or borders between and around the controls:

After moving or scaling a control or its parent node, and after adjusting the Camera and screen adaptation modes, check the replay results in native Android and iOS runtime environments: the mask should follow the target position, fully cover the sensitive content, and not extend to other controls beyond the target rectangle. Rectangle edges are rounded to the captured pixel grid, so also check whether content leaks or is accidentally masked at the edges.

Network Data¶

When autoTrack.network is enabled, URLs, request headers, response headers, HTTP methods, and status codes are collected.

Pay special attention to:

• Accounts, tokens, or business IDs in the 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 request bodies or response bodies. The responseBody in manual addResource() is handled as passed in by the business. Do not pass it by default; sanitize and truncate it first when troubleshooting is truly needed.

Log and Console¶

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

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

For production environments, keep console: false and use guanceSdk.logger.log() to report filtered content.

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

Error¶

Error messages and stacks may contain:

• URLs;
• File paths;
• User input;
• String representations of business objects.

Before manually calling addError(), clean sensitive values from the message, stack, and attributes. Automatic error monitoring cannot provide a sanitization callback. If the exception content in the application is uncontrollable, disable autoTrack.errors and report manually after sanitizing at business error boundaries.

Users and Custom Tags¶

• Use an internal irreversible identifier for userId; do not use phone numbers or email addresses as the ID.
• Pass userEmail only when the business truly needs it.
• Add only low-sensitivity, stable, and 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, exposing internal tracing relationships. If automatic network tracing cannot filter by domain, use trace.getHeaders() to manually control the injection scope.

Pre-Release Checks¶

1. Cover sensitive scenarios such as login, payment, chat, and account settings on real devices.
2. Check the URLs and headers of RUM Resources.
3. Check error messages, stacks, and custom attributes.
4. Check Console and custom logs.
5. Replay Session Replay to confirm that input fields and custom sensitive areas are masked.
6. Verify that Trace headers are sent only to allowed domains.