콘텐츠로 이동

데이터 및 프라이버시

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

기본 원칙

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

Session Replay

기본 규칙

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

ReplayPrivacy 컴포넌트 사용

씬 또는 프리팹의 민감한 노드에는 ReplayPrivacy 컴포넌트로 마스크를 구성하는 것을 우선 권장합니다. Creator 2 및 Creator 3 모두 이 컴포넌트를 지원합니다.

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

  2. 설치 프로그램은 Creator 메이저 버전에 따라 컴포넌트 스크립트를 assets/guance-cocos-sdk/ReplayPrivacy.ts에 복사합니다. Cocos Creator를 다시 열고 대상 노드의 컴포넌트 메뉴에서 Session Replay > ReplayPrivacy를 선택하거나 스크립트를 인스펙터로 끌어다 놓습니다.

  3. 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를 사용해야 합니다.

자동 네트워크 수집은 요청 Body와 응답 Body를 읽지 않습니다. 수동 addResource()의 responseBody는 비즈니스에서 전달한 내용 그대로 처리되므로 기본적으로 전달하지 않아야 하며, 실제 조사가 필요할 때는 먼저 마스킹과 길이 제한을 적용해야 합니다.

Log 및 Console

autoTrack.console은 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는 신뢰하는 비즈니스 도메인에만 주입해야 합니다. 타사 도메인이 Trace 식별자를 수신하면 내부 추적 관계가 노출될 수 있습니다. 자동 네트워크 추적을 도메인별로 필터링할 수 없는 경우 trace.getHeaders()를 사용하여 주입 범위를 수동으로 제어해야 합니다.

출시 전 점검

  1. 실기기에서 로그인, 결제, 채팅, 계정 설정 등 민감한 시나리오를 점검합니다.
  2. RUM Resource의 URL과 Header를 확인합니다.
  3. Error Message, Stack 및 커스텀 속성을 확인합니다.
  4. Console 및 커스텀 로그를 확인합니다.
  5. Session Replay 재생을 통해 입력 필드와 커스텀 민감 영역이 마스킹되었는지 확인합니다.
  6. Trace Header가 허용된 도메인에만 전송되는지 확인합니다.

문서 평가

이 페이지가 도움이 되었나요?