Cocos Creator 세션 리플레이(실험적)¶

이 문서에서는 Cocos Creator Session Replay 초기화, Camera 선택, 성능 파라미터, 터치 프라이버시, 노드 프라이버시 규칙을 설명합니다.

사전 요구 사항¶

Session Replay에는 다음이 필요합니다:

1. Android 또는 iOS 네이티브 빌드;
2. RUM 초기화 완료;
3. 유효한 RUM View가 활성 상태;
4. 현재 SDK 버전 조합의 Cocos SDK 및 네이티브 의존성 사용.

유효한 RUM Context가 없으면 SDK는 현재 프레임을 건너뛰며, RUM과 별개의 리플레이 데이터를 생성하지 않습니다. autoTrack.scenes를 활성화하거나, 프레임 캡처 전에 guanceSdk.rum.startView()를 수동으로 호출하세요.

독립 Replay 패키지 설치¶

Cocos SDK 0.1.0-alpha.6부터 세션 리플레이는 @cloudcare/cocos-session-replay에서 별도로 제공됩니다. Cocos 프로젝트 루트에서 동일한 버전의 두 패키지를 설치하세요:

npm install @cloudcare/cocos-sdk@0.1.0-alpha.7 @cloudcare/cocos-session-replay@0.1.0-alpha.7
npx --no-install guance-cocos install --project . --replay

Creator를 다시 열고 네이티브 프로젝트를 생성 및 컴파일하세요. CocoaPods를 사용하는 iOS 프로젝트는 pod install도 실행해야 합니다. SPM 구성 및 스위치 유지 규칙은 앱 연동을 참조하세요.

기본 패키지에는 Replay API, 프레임 캡처 구현, Replay 네이티브 의존성이 포함되지 않습니다. 아래 예시는 조합된 인스턴스를 observability.ts에서 내보낸 guanceSdk로 저장하며, 다른 모듈에서 이 인스턴스를 재사용합니다.

초기화¶

import { guanceSdk as baseSdk } from '@cloudcare/cocos-sdk/creator3';
import { withSessionReplay } from '@cloudcare/cocos-session-replay/creator3';

export const guanceSdk = withSessionReplay(baseSdk);

guanceSdk.start({
  ...,
  rum: {
    androidAppId: 'android-rum-app-id',
    iosAppId: 'ios-rum-app-id',
  },
  replay: {
    sampleRate: 1,
    sessionOnErrorSampleRate: 0,
    captureFps: 2,
    maxImageDimension: 720,
    imagePolicy: {
      quality: 'medium',
    },
    touchPrivacy: 'show',
  },
  autoTrack: {
    scenes: true,
  },
});

Creator 2에서는 두 패키지의 import 진입점을 모두 /creator2로 변경하세요. 조합은 SDK 초기화 또는 Hybrid attach() 이전에 이루어져야 합니다. 이후의 .replay, start({ replay }), attach({ replay })는 모두 조합된 인스턴스에서 호출합니다.

잘못된 샘플링 비율, FPS, 이미지 크기 또는 트래픽 정책은 TypeScript 계층에서 TypeError 또는 RangeError를 발생시킵니다.

이미지 크기 정책¶

captureFps는 목표 프레임 캡처 빈도를 별도로 제어하고, imagePolicy는 이미지 인코딩 품질과 단일 프레임 크기를 제어합니다. 단일 프레임 제한이 필요하면 imagePolicy를 명시적으로 전달해야 합니다:

replay: {
  captureFps: 3,
  maxImageDimension: 720,
  imagePolicy: {
    quality: 'medium',
    maxFrameBytes: 40 * 1024,
  },
}

imagePolicy는 다음 필드를 지원합니다:

명시적으로 설정된 maxImageDimension와 imagePolicy.maxFrameBytes는 프리셋을 덮어씁니다. Android V2는 WebP를, iOS V2는 JPEG를 사용합니다. 인코딩 후 제한을 초과하면 먼저 품질을 낮추고, 그다음 크기를 줄입니다. 그래도 초과하면 해당 이미지는 저장하지 않지만, 대기 중인 터치 기록은 계속 저장할 수 있습니다.

0.1.0-alpha.7에서는 이미지 롤링 60초 예산, 예산에 따른 캡처 빈도 감소, 100 KiB 첫 프레임 버스트 허용량이 제거되었습니다. 업그레이드 시 imagePolicy.maxBytesPerMinute, imagePolicy.adaptiveCapture를 삭제하세요. 이 두 필드는 더 이상 구성 API에 속하지 않습니다. captureFps는 목표 빈도이며, 프레임 중복 제거, 프레임 캡처, 인코딩 소요 시간은 여전히 실제 출력에 영향을 줄 수 있습니다. SDK는 매번 한 프레임만 처리하며, 캡처 슬롯을 초과하면 지나친 슬롯을 건너뛰고 동시 작업을 쌓아 두지 않습니다.

imagePolicy를 전달하지 않으면 기존 이미지 경로가 유지되며 인코딩 바이트 상한이 없으므로 위의 단일 프레임 상한을 적용할 수 없습니다. imagePolicy: {}를 전달하면 medium 프리셋이 적용됩니다. 명시적으로 활성화하면 네이티브 V2 이미지 인터페이스가 필요합니다. 인터페이스를 사용할 수 없거나 이미지가 제한을 초과하면 오류를 보고하며, 크기 제한을 보장할 수 없는 이전 인터페이스로 대체되지 않습니다.

Camera 선택¶

기본적으로 현재 씬에서 찾은 첫 번째 Camera를 사용합니다. 다중 Camera 프로젝트는 리플레이할 Camera를 명시적으로 지정해야 합니다:

import { guanceSdk } from './observability';

export function selectReplayCamera(camera: unknown): void {
  guanceSdk.setReplayCamera(camera);
}

setReplayCamera()는 호출할 때마다 하나의 Camera만 저장합니다. 여러 번 호출하면 나중에 전달된 Camera가 이전 설정을 덮어쓰며, SDK는 여러 Camera를 동시에 캡처하거나 합성하지 않습니다. 호출 시 이전 프레임이 캡처 중이면 새 Camera는 다음 캡처부터 적용됩니다.

메인 Camera를 전환한 후에는 setReplayCamera()를 다시 호출해야 합니다. 씬에 사용 가능한 Camera가 없으면 현재 프레임은 건너뜁니다.

0.1.0-alpha.7에서 Creator 3는 별도의 오프스크린 Camera로 프레임을 캡처하여 표시 Camera의 렌더 타겟을 수정하거나 Camera에 의존하는 입력 좌표에 영향을 주지 않습니다. 이 조정은 단일 Camera 캡처 제한을 변경하지 않습니다. 업그레이드 후에도 다중 Camera, 화면 방향 변경, 노드 마스크 표시 효과를 검증해야 합니다.

터치 프라이버시¶

touchPrivacy는 Session Replay에서 터치 위치 기록 여부를 제어합니다:

터치 캡처는 Session Replay에 속하며 autoTrack.actions와 독립적입니다. autoTrack.actions가 꺼져 있어도 touchPrivacy: 'show'이면 Replay 터치가 기록됩니다. 반대로 Action 자동 캡처를 켜고 touchPrivacy: 'hide'를 유지하면 Replay에 터치 위치가 나타나지 않습니다. 전후 프레임 화면이 동일하더라도 대기 중인 터치 조작은 Replay에 별도로 저장됩니다.

0.1.0-alpha.7에서는 Creator 3에서 UI 컨트롤이 소비한 터치가 Replay에서 누락되던 문제를 수정하고 정상적인 입력 전달을 유지합니다. touchPrivacy: 'show'를 활성화한 경우 버튼, 조이스틱 등 컨트롤의 비즈니스 응답과 Replay 터치 위치를 함께 검증하여 조작이 중복 기록되지 않는지 확인하세요. 이 수정은 autoTrack.actions의 캡처 범위를 확장하지 않습니다.

현재 Cocos API는 전역 터치 프라이버시 설정만 지원하며 노드별 터치 프라이버시 재정의는 지원하지 않습니다. guanceSdk.replay.setPrivacy(node, 'hide')는 노드 화면만 숨기며 해당 위치의 터치 기록은 숨기지 않습니다. 민감한 페이지에서는 Session Replay 시작 시 touchPrivacy: 'hide'를 사용하세요.

노드 프라이버시¶

모든 EditBox 노드는 기본적으로 mask를 사용합니다. 지정된 노드에 규칙을 설정할 수도 있습니다:

guanceSdk.replay.setPrivacy(accountNode, 'mask');
guanceSdk.replay.setPrivacy(secretPanelNode, 'hide');
guanceSdk.replay.setPrivacy(publicNode, 'unmask');

unmask는 사용자 지정 규칙만 삭제합니다. 노드가 여전히 EditBox이면 기본 마스크가 계속 적용됩니다.

프라이버시 영역은 노드의 월드 좌표 사각형 기준으로 계산됩니다. 사용자 지정 렌더링, 파티클, Shader, RenderTexture 또는 노드 경계 상자를 벗어난 시각적 콘텐츠는 프라이버시 영역이 자동으로 유추되지 않으므로, 연동 테스트에서 씬별로 확인해야 합니다.

페이지별 마스크 관리¶

setPrivacy()의 규칙은 전달된 노드 인스턴스에 바인딩되며, 페이지 이름이나 RUM View에 따라 자동으로 전환되지 않습니다. 페이지마다 다른 콘텐츠를 마스크해야 하는 경우, 비즈니스 페이지의 진입/이탈 로직에서 각 노드의 규칙을 관리해야 합니다.

아래는 동일한 씬에서 '진단 페이지'와 '조작 페이지'를 전환하는 예시입니다. diagnosticsPage, motionPage는 두 페이지의 루트 노드이고, privateTokenNode는 진단 페이지 내에서 마스크해야 하는 일반 노드입니다. SDK 초기화 또는 Hybrid attach()가 완료된 후 페이지를 전환할 때 해당 함수를 호출하세요:

function showDiagnostics() {
  // 매번 진입할 때 다시 설정하여 민감 노드가 표시되기 전에 마스크 규칙이 있도록 합니다.
  guanceSdk.replay.setPrivacy(privateTokenNode, 'mask');
  motionPage.active = false;
  diagnosticsPage.active = true;
}

function showMotion() {
  // 민감 페이지를 먼저 숨긴 뒤 해당 페이지 노드의 사용자 지정 규칙을 제거합니다.
  diagnosticsPage.active = false;
  guanceSdk.replay.setPrivacy(privateTokenNode, 'unmask');
  motionPage.active = true;
}

조작 페이지에도 민감 노드가 있다면 표시 전에 해당 노드마다 mask 또는 hide를 설정하고, 이탈할 때 해당 규칙을 제거해야 합니다. 한 페이지에 여러 개의 사용자 지정 마스크 노드가 있으면 각각 관리해야 합니다.

페이지 생명 주기에서 다음 사항도 유의하세요:

• 페이지나 부모 노드를 active = false로만 설정하면 등록된 사용자 지정 규칙이 삭제되지 않습니다. 페이지 숨김은 unmask 호출을 대체할 수 없으며, 그렇지 않으면 이전 페이지의 마스크 영역이 이후 화면에 영향을 줄 수 있습니다.
• 페이지를 떠나거나 노드가 파괴되기 전에 해당 페이지에 등록된 사용자 지정 규칙을 제거하세요. 로직은 프로젝트의 페이지 매니저 또는 컴포넌트의 활성화/비활성화/파괴 콜백에 둘 수 있습니다.
• 페이지에 다시 진입할 때 규칙을 다시 설정하세요. 페이지가 파괴된 후 재생성된 경우 새로 생성된 노드 인스턴스를 전달해야 합니다.
• RUM View 이름을 전환해도 노드 규칙이 자동으로 설정되거나 지워지지 않습니다. Hybrid enterCocos() / leaveCocos()는 캡처 소속을 관리하며, 페이지는 여전히 자체적으로 노드 마스크를 관리해야 합니다.
• unmask는 지정된 노드의 사용자 지정 규칙만 삭제하며, 전역 프라이버시 보호를 끄거나 EditBox 기본 마스크를 해제하지 않습니다.

이 규칙은 Cocos 프레임 캡처의 노드 화면에 영향을 줍니다. Hybrid 네이티브 페이지는 여전히 호스트 Native SDK의 Session Replay 프라이버시 구성을 사용하며, 터치 위치는 touchPrivacy가 별도로 제어합니다.

검증 시 '페이지 진입 → 다른 페이지로 전환 → 다시 진입'을 포함하여, Replay에서 민감 콘텐츠가 계속 마스크되고 다른 페이지에 잔여 마스크가 없는지 확인하세요.

더 많은 프라이버시 권장 사항은 데이터 및 프라이버시를 참조하세요.

실행 동작¶

• Cocos RenderTexture를 사용하여 RGBA 화면을 캡처합니다.
• imagePolicy를 구성하지 않으면 기존 이미지 경로를 유지합니다. 명시적으로 구성하면 Android는 WebP V2, iOS는 JPEG V2를 사용하고 실제 인코딩 크기를 확인합니다.
• 프라이버시 마스크는 이미지 압축 전에 적용됩니다.
• 내용이 완전히 동일하거나 거의 정적인 프레임은 건너뜁니다. View, 화면 크기 또는 프라이버시 규칙이 변경되면 변경 프레임이 강제로 생성됩니다.
• 이미지가 중복 제거 또는 인코딩 크기로 건너뛰어도 대기 중인 터치 기록은 별도로 저장됩니다.
• 이전 프레임이 아직 처리 중이면 새 프레임을 동시에 처리하지 않습니다.
• 단일 프레임 캡처 또는 인코딩 실패 시 현재 프레임만 버리고 이후 Session Replay 캡처는 중단하지 않습니다.
• 임시 이미지는 Native SDK에 기록된 후 앱 임시 디렉터리에서 삭제됩니다.

트래픽 계산¶

아래는 녹화된 단일 세션의 이미지 페이로드만 계산합니다. 1 KiB = 1024 bytes, 1 MiB = 1048576 bytes입니다. Replay Segment, 터치 메타데이터, 업로드 프로토콜 오버헤드, 재시도는 별도로 산정해야 합니다.

계산 방식¶

실측 이미지 트래픽(MiB/분) = 중복 제거 후 이미지 총 바이트 수 ÷ 해당 기록 시간(초) × 60 ÷ 1048576
계획 이미지 트래픽(MiB/분) ≈ 평균 인코딩 바이트 수 × 분당 예상 저장 이미지 수 ÷ 1048576
전체 프레임 이미지 이론 상한(MiB/분) ≈ maxFrameBytes × captureFps × 60 ÷ 1048576

반복 재생으로 인한 다운로드는 이미지 리소스 ID로 중복 제거됩니다. 동일한 이미지를 재사용하는 여러 레코드는 리소스 크기를 중복 합산하지 않습니다. 통계 시간과 이미지 집합은 서로 대응해야 하며, 전체 Replay의 이미지 총량을 특정 View의 시간으로 나눌 수 없습니다. 클라우드에서 다운로드한 것은 이미지 페이로드 크기이며, 실제 업로드 총 트래픽은 기기에서 측정해야 합니다.

6가지 구성의 전체 프레임 이론 상한¶

표는 모든 프레임이 저장되고 단일 프레임 크기 상한에 도달한다고 가정한 근사적인 전체 프레임 이미지 상한이며, 일반적인 소비량, 총 업로드 상한 또는 롤링 할당량이 아닙니다. 예를 들어 medium, 3 FPS의 이론 이미지 상한은 40960 × 3 × 60 ÷ 1048576 ≈ 7.03 MiB/분이며, 실제 이미지는 일반적으로 40 KiB보다 작습니다.

6가지 구성의 샘플 추정 범위¶

아래 표는 기존 Battle 이미지 21장을 libwebp 1.6.0으로 Android 정책에 따라 다시 인코딩하고, 최소/최대 이미지 크기에 분당 120장 또는 180장을 각각 곱해 추정한 것입니다. 값의 하한은 이 동적 샘플의 참조 하한을 나타내며 모든 시나리오의 최소 트래픽은 아닙니다.

이 값은 이미 압축된 이미지를 다시 인코딩한 추정치이며, 6가지 구성 각각에 대해 연속 실기기 녹화를 수행한 것은 아닙니다. low는 480×270으로 축소되었고, medium/high는 720×405 원본 이미지를 사용했으며 확대하지 않았으므로 high 데이터는 960px 프레임 캡처의 트래픽을 의미하지 않습니다. 이 표는 iOS JPEG 트래픽을 추론하는 데 사용할 수 없으며 다른 시나리오의 보장 범위도 아닙니다.

Android 실기기 참고¶

2026년 9월 13일, Guance Cocos 개발 패키지의 Creator 2.4.9 Android 예시에서 Battle 씬은 captureFps: 3, quality: 'medium', 최대 변 720px, 프레임당 40KiB 상한을 사용했습니다. 해당 씬의 WebP 이미지 83장이 모두 확보되었습니다:

이 측정은 Guance 개발 패키지의 기기 참고 자료이며, TrueWatch 실기기 트래픽 테스트가 별도로 수행되었음을 의미하지 않습니다. 이 Android Battle 씬에서는 약 2.0–2.1 MiB/분을 이미지 용량 계획 참고 값으로 사용할 수 있습니다. 이 실기기 결과는 앞선 표의 medium 재인코딩 추정치보다 약간 높으므로 실기기 데이터를 우선 사용해야 합니다. low/high는 여전히 샘플 재인코딩 추정치일 뿐이며, 이를 근거로 실기기 검증이 완료되었다고 말할 수 없습니다.

전체 리플레이 원본 기록의 시간 간격은 68.953초이며, 콘솔 세션 헤더에는 48.15초로 표시됩니다. 해당 원본 기록 시간을 기준으로 계산해야 합니다. Battle 외에 이미지 2장을 서버에서 가져오지 못했으므로, 전체 다운로드 총량은 전체 업로드 트래픽의 참고 값으로 사용할 수 없습니다. 이미지 누락, 프로토콜 오버헤드, 재시도는 위 이미지 추정만으로 유추할 수 없습니다.

세션 샘플링 및 전체 용량¶

화면이 완전히 동일하거나 거의 정적인 경우 중복 제거로 이미지 수가 줄어듭니다. 캡처 및 인코딩 소요 시간도 실제 프레임 레이트를 낮출 수 있습니다. 프로덕션 용량은 대상 기기와 실제 시나리오의 평균 이미지 크기 및 저장 빈도로 추정하고, 고역동 화면, 메뉴, 정적 페이지를 각각 측정해야 합니다.

세션 샘플링은 녹화에 참여하는 세션 수를 제어하며, 개별 녹화 세션의 이미지 제한을 변경하지 않습니다. 세션이 균일하게 샘플링되고 녹화 시간과 씬 분포가 유사하다면 일반 샘플링 부분을 대략적으로 추정할 수 있습니다:

전체 이미지 트래픽 ≈ 총 세션 분 수 × sampleRate × 녹화된 세션 평균 이미지 트래픽/분

RUM 샘플링과 실제 녹화에 참여한 분 수를 함께 고려해야 합니다. 오류 세션 추가 샘플링으로 인한 녹화, Segment, 네트워크 오버헤드는 별도로 산정합니다. 정확한 과금 또는 네트워크 용량 데이터가 필요하면 기기 측 업로드 통계를 기준으로 합니다.

alpha.7로 업그레이드¶

Cocos 프로젝트 루트에서 기본 패키지와 Replay 패키지를 동시에 업그레이드하고 네이티브 연동을 업데이트하세요:

npm install @cloudcare/cocos-sdk@0.1.0-alpha.7 @cloudcare/cocos-session-replay@0.1.0-alpha.7
npx --no-install guance-cocos install --project . --replay

• 이미 alpha.6 패키지 분리 API를 사용하는 프로젝트는 withSessionReplay(baseSdk)가 반환한 인스턴스를 계속 재사용합니다.
• imagePolicy.maxBytesPerMinute와 imagePolicy.adaptiveCapture를 삭제하세요. captureFps로 빈도를 제어하고, maxImageDimension와 imagePolicy.maxFrameBytes로 이미지별 크기를 제어합니다. 기존 JavaScript 구성에 제거된 필드를 유지해도 분 예산이 활성화되지 않습니다.
• 모든 이미지는 새 View 및 화면 방향 변경의 첫 프레임을 포함해 단일 프레임 상한을 적용받습니다. 롤링 예산에 따른 빈도 감소와 첫 프레임 전용 버스트 허용량은 더 이상 제공되지 않습니다. 실제 트래픽을 다시 평가하세요. 트래픽 계산을 참조하십시오.
• Creator를 다시 열고 네이티브 프로젝트를 생성 및 컴파일하세요. CocoaPods를 사용하면 pod install을 다시 실행하세요. JavaScript만 교체해서는 네이티브 이미지 처리 로직이 업데이트되지 않습니다.
• Creator 3의 표시 화면, 버튼 및 조이스틱 응답, Replay 터치 위치를 검증하고 View 전환, 가로/세로 화면 변경, 프라이버시 마스크를 확인하세요.

통합 패키지에서 마이그레이션¶

0.1.0-alpha.5 또는 이전 버전에서 업그레이드하는 경우:

1. 기본 패키지를 공개된 0.1.0-alpha.6 이상으로 업그레이드하고, 동일 버전의 Replay 패키지를 설치한 후 설치 프로그램 --replay를 다시 실행하세요.
2. 첫 start() / attach() 전에 withSessionReplay(baseSdk)를 호출하여 비즈니스 코드가 조합된 인스턴스를 재사용하도록 하세요.
3. 기존에 별도로 내보냈던 setReplayCamera(camera)를 guanceSdk.setReplayCamera(camera)로 변경하세요.
4. FTSessionReplayConfig, FTHybridSessionReplayConfig, FTReplayImagePolicy 등 Replay 타입의 import를 @cloudcare/cocos-session-replay/creator2 또는 /creator3로 이동하세요. Replay를 포함한 전체 구성은 각각 FTCocosReplayConfig와 FTCocosHybridReplayConfig를 사용합니다.
5. 네이티브 프로젝트를 다시 생성하고 컴파일하세요. JavaScript만 교체하면 새 Replay Bridge가 설치되지 않습니다.

Replay를 더 이상 사용하지 않으면 조합과 Replay 구성을 제거하고 설치 프로그램 --no-replay를 실행한 후 다시 빌드하세요. 이 스위치는 설치 프로그램이 관리하는 네이티브 연동을 제거하는 데 사용됩니다. 런타임에 프레임 캡처를 일시 중지하려면 아래의 replay.stop()을 사용하고, Hybrid 시나리오에서는 leaveCocos()를 사용합니다.

시작 및 중지¶

Replay 패키지를 설치하고 조합한 상태에서 guanceSdk.start()에 replay를 전달하지 않았더라도, RUM 초기화 및 View 시작 후 별도로 활성화할 수 있습니다:

guanceSdk.replay.start({
  sampleRate: 1,
  captureFps: 1,
  maxImageDimension: 720,
  touchPrivacy: 'show',
});

프레임 캡처 중지:

guanceSdk.replay.stop();

guanceSdk.shutdown()도 프레임 캡처를 중지합니다. guanceSdk.start({ replay: ... })와 guanceSdk.replay.start()를 동시에 사용하여 중복 시작하지 마세요.

네이티브 호스트 Hybrid 모드에서는 위의 시작/중지 인터페이스를 사용하지 않습니다. Session Replay는 네이티브 호스트가 네이티브 recorder 모드로 초기화하며, Cocos는 enterCocos()와 leaveCocos() 사이에서 외부 캡처 소스로 자동 전환됩니다. 자세한 내용은 네이티브 호스트 Hybrid 연동을 참조하세요.

성능 권장 사항¶

• captureFps: 1, imagePolicy: { quality: 'medium' }부터 검증하고, 더 부드러운 화면이 필요하면 2 fps로 높이세요.
• 리플레이가 필요한 비즈니스 환경에서만 샘플링을 활성화하세요.
• 저사양 기기에서 GPU, 메모리 또는 디스크 부담이 발생하면 먼저 low로 변경하고, 그다음 최대 변 크기와 샘플링 비율을 낮추세요.
• 가로/세로 화면 전환, 다중 Camera, 복잡한 UI, 낮은 프레임 레이트 시나리오에서 이미지 방향과 마스크 위치를 검증하세요.