데이터 및 개인정보 보호¶

이 문서는 Cocos Creator SDK가 RUM, 로그, Trace 및 Session Replay에서 다룰 수 있는 민감 데이터 범위를 설명합니다.

기본 원칙¶

성능 및 안정성 문제를 파악하는 데 필요한 데이터만 수집합니다.
비밀번호, 인증 코드, 토큰, 전체 주민등록번호, 은행카드 번호 등 민감 정보를 수집하지 않습니다.
테스트 환경에서 자동 수집을 활성화한 후 실제 전송 내용을 확인한 다음 프로덕션 구성을 결정합니다.
사용자 정의 태그, 로그, 수동 Resource Body의 비식별화는 비즈니스 측에서 담당합니다.

Session Replay¶

기본 규칙¶

모든 EditBox 노드는 기본적으로 mask를 사용합니다.
중복 프레임과 처리 중인 프레임은 건너뜁니다.
프레임 캡처는 Native Bridge에 들어가기 전에 노드 사각형 마스크를 적용합니다.

ReplayPrivacy 컴포넌트 사용¶

씬 또는 프리팹에 있는 민감 노드의 경우 ReplayPrivacy 컴포넌트를 우선 사용하여 마스크를 구성하세요. Creator 2와 Creator 3 모두 이 컴포넌트를 지원합니다.

SDK를 설치한 후 Cocos 프로젝트 루트 디렉터리에서 프로젝트 설치 프로그램을 다시 실행합니다.

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

설치 프로그램은 Creator 주 버전에 따라 컴포넌트 스크립트를 assets/guance-cocos-sdk/ReplayPrivacy.ts에 복사합니다. Cocos Creator를 다시 열고 대상 노드의 컴포넌트 메뉴에서 Session Replay > ReplayPrivacy를 선택하거나 스크립트를 인스펙터로 드래그합니다.
Mode를 Mask(기본, 회색 마스크) 또는 Hide(검은색 마스크)로 설정하고 씬 또는 프리팹을 저장합니다.

컴포넌트는 Session Replay 프레임 캡처에만 영향을 주며, 앱에서 실시간으로 표시되는 노드는 변경하지 않습니다. SDK는 매 프레임 캡처 시 현재 씬에서 유효하고 활성화된 컴포넌트를 인식하며, 여기에는 런타임에 인스턴스화된 프리팹도 포함됩니다. 컴포넌트를 비활성화하거나 제거하면 해당 규칙은 더 이상 적용되지 않습니다. 노드의 코드 규칙과 EditBox 기본 규칙은 계속 유지됩니다.

스크립트의 ReplayPrivacy 클래스 이름과 .meta 파일을 유지하여 씬 또는 프리팹의 컴포넌트 참조가 깨지지 않도록 하세요. Creator 3에서 대상 UI 노드는 마스크 경계를 제공하는 UITransform을 갖추고 있어야 합니다.

코드로 추가 규칙 적용¶

컴포넌트를 추가하기 어려운 노드나 동적 덮어쓰기가 필요한 시나리오에서는 setPrivacy()를 사용합니다.

다음 guanceSdk는 withSessionReplay()로 조합한 인스턴스를 가리킵니다. 기본 패키지 자체는 .replay를 제공하지 않습니다.

guanceSdk.replay.setPrivacy(passwordPanel, 'hide'); // 검은색 마스크
guanceSdk.replay.setPrivacy(playerName, 'mask'); // 회색 마스크
guanceSdk.replay.setPrivacy(playerName, 'unmask'); // 코드 오버라이드 제거

같은 노드의 규칙 우선순위는 setPrivacy() 코드 규칙 > ReplayPrivacy 컴포넌트 규칙 > EditBox 기본 마스크입니다.

unmask는 이전에 설정된 코드 규칙만 제거하며, 이후 컴포넌트 규칙 또는 EditBox 기본 규칙으로 복원합니다. 민감 콘텐츠를 강제로 표시하지 않습니다. 예를 들어 노드 컴포넌트가 Hide로 설정된 후 setPrivacy(node, 'mask')를 호출하면 회색 마스크로 변경되고, 다시 setPrivacy(node, 'unmask')를 호출하면 검은색 마스크로 복원됩니다. 따라서 컴포넌트의 Mode는 Mask와 Hide만 제공합니다.

코드로 여러 페이지의 마스크를 관리할 때는 페이지에 진입할 때 설정하고, 이탈하거나 파괴되기 전에 unmask로 제거한 후 다시 진입할 때 복원해야 합니다. 페이지를 숨기기만 하면 등록된 코드 규칙이 삭제되지 않습니다. 전체 예시는 페이지별 마스크 관리를 참조하세요.

현재 Replay 구성은 maskInputs 스위치를 제공하지 않으므로 EditBox 기본 마스크를 이 필드로 끌 수 없습니다.

마스크 범위 및 검증¶

마스크는 노드의 월드 좌표 경계 상자를 기준으로 프레임 캡처 Camera를 통해 스크린샷의 사각형 영역에 투영됩니다. 특정 민감 컨트롤만 가려야 한다면 해당 컨트롤에 컴포넌트를 추가하고 노드 경계가 대상 영역에 밀착되도록 하세요.

예를 들어 같은 페이지에 민감 컨트롤 세 개를 나란히 배치하고 컨트롤 사이와 주변에 공개 텍스트나 테두리를 유지합니다.

대상 컨트롤	구성 방법	예상 리플레이 결과
플레이어 닉네임	`ReplayPrivacy` 추가, Mode를 Mask로 설정	대상 사각형 영역이 회색으로 표시됨
계정 정보	`ReplayPrivacy` 추가, Mode를 Hide로 설정	대상 사각형 영역이 검은색으로 표시됨
동적 민감 콘텐츠	`setPrivacy(node, 'mask')` 호출	대상 사각형 영역이 회색으로 표시됨
사각형 영역 외부의 공개 텍스트, 테두리	개인정보 규칙 미설정	표시 유지, 인접 컨트롤의 마스크에 가려지지 않음

컨트롤 또는 부모 노드를 이동하거나 크기를 조정하고 Camera와 화면 적응 모드를 조정한 후, Android 및 iOS 네이티브 실행 환경에서 각각 리플레이 결과를 확인하세요. 마스크는 대상 위치를 따라 민감 콘텐츠를 완전히 덮어야 하며, 대상 사각형 밖의 다른 컨트롤로 확장되지 않아야 합니다. 사각형 가장자리는 프레임 캡처 픽셀 단위로 반올림되므로, 가장자리에서 콘텐츠 누출이나 잘못된 가림이 없는지 함께 확인하세요.

마스크 경계

마스크는 스크린샷의 사각형 영역을 덮습니다. 사각형 안의 하위 노드와 기타 겹치는 콘텐츠도 함께 가려집니다. 하위 노드의 unmask는 상위 노드가 이미 덮은 픽셀을 취소할 수 없습니다. 따라서 일부만 가리면 되는 콘텐츠를 위해 페이지 전체 컨테이너를 선택하지 마세요.

Shader, 파티클, RenderTexture, 사용자 정의 드로잉, 경계 상자를 벗어난 콘텐츠 및 기타 Camera 화면은 덮이지 않을 수 있습니다. 실제 기기에서 씬별로 리플레이 결과를 확인하세요.

네트워크 데이터¶

autoTrack.network를 활성화하면 URL, 요청 헤더, 응답 헤더, HTTP 메서드 및 상태 코드를 수집합니다.

특히 다음을 중점적으로 확인해야 합니다.

URL Query의 계정, 토큰 또는 비즈니스 ID
Authorization, Cookie 및 사용자 정의 인증 요청 헤더
응답 헤더의 사용자 또는 테넌트 정보

현재 Cocos API는 URL 또는 Header 필터링 콜백을 제공하지 않습니다. 네트워크 프로토콜에 민감 필드가 포함된 경우 자동 네트워크 수집을 끄고 허용된 요청에만 수동 Resource 및 Trace API를 사용하세요.

자동 네트워크 수집은 요청 본문과 응답 본문을 읽지 않습니다. 수동 addResource()의 responseBody는 비즈니스에서 전달한 내용 그대로 처리되므로 기본적으로 전달하지 마세요. 문제 해결이 반드시 필요한 경우에는 비식별화와 길이 제한을 먼저 적용하세요.

로그 및 콘솔¶

autoTrack.console은 콘솔 파라미터를 텍스트로 변환하며 다음이 포함될 수 있습니다.

디버그 토큰
전체 인터페이스 객체
사용자 입력
계정 및 디바이스 식별자
예외 객체의 비즈니스 데이터

프로덕션 환경에서는 console: false를 유지하고 guanceSdk.logger.log()로 필터링된 콘텐츠를 전송하세요.

민감 객체를 로그 attributes에 직접 넣지 마세요. 객체는 JSON 직렬화된 후 로그 데이터에 포함됩니다.

Error¶

Error Message 및 Stack에는 다음이 포함될 수 있습니다.

URL
파일 경로
사용자 입력
비즈니스 객체의 문자열 결과

addError()를 직접 호출하기 전에 메시지, 스택, 속성의 민감 값을 정리하세요. 자동 오류 리스너는 비식별화 콜백을 제공하지 않습니다. 애플리케이션의 예외 콘텐츠를 제어할 수 없다면 autoTrack.errors를 끄고, 비즈니스 오류 경계에서 비식별화한 후 수동으로 전송하세요.

사용자 및 사용자 정의 태그¶

userId는 내부 비가역 식별자를 사용하고 휴대폰 번호나 이메일을 ID로 사용하지 않는 것이 좋습니다.
userEmail은 비즈니스에서 반드시 필요한 경우에만 전달합니다.
extra와 모든 globalContext에는 민감도가 낮고 안정적이며 필터링에 사용할 수 있는 태그만 추가합니다.
카디널리티가 높은 필드나 요청마다 변경되는 콘텐츠는 전역 태그로 설정하지 마세요.

Trace Header¶

Trace Header는 신뢰할 수 있는 비즈니스 도메인에만 주입해야 합니다. 제3자 도메인이 Trace 식별자를 수신하면 내부 추적 관계가 노출될 수 있습니다. 자동 네트워크 추적에서 도메인별 필터링이 불가능한 경우 trace.getHeaders()를 사용하여 주입 범위를 수동으로 제어하세요.

배포 전 점검¶

실제 기기에서 로그인, 결제, 채팅, 계정 설정 등 민감 시나리오를 점검합니다.
RUM Resource의 URL과 Header를 확인합니다.
Error Message, Stack 및 사용자 정의 속성을 확인합니다.
콘솔 및 사용자 정의 로그를 확인합니다.
Session Replay를 재생하여 입력란과 사용자 정의 민감 영역이 마스킹되었는지 확인합니다.
Trace Header가 허용된 도메인에만 전송되는지 확인합니다.