Cocos Creator セッションリプレイ（実験的）¶

この記事では、Cocos Creator セッションリプレイの初期化、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 プロジェクトのルートで、完全に同じバージョンの2つのパッケージをインストールしてください：

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 では、両方のパッケージのインポートエントリを /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 は毎回1フレームのみを処理し、収集スロットを超えた場合は過ぎたスロットをスキップし、同時タスクを積み上げません。

imagePolicy を渡さない場合は従来の画像パスが維持され、エンコード後のバイト数上限はなく、上記の単一フレーム上限は適用されません。imagePolicy: {} を渡すと medium プリセットが採用されます。明示的に有効にすると、ネイティブの V2 画像インターフェースが必要になります。インターフェースが利用できない場合や上限を超える画像が返された場合はエラーが報告され、サイズ制限を保証できない従来のインターフェースにフォールバックしません。

Camera の選択¶

デフォルトでは、現在のシーンで見つかった最初の Camera が使用されます。複数の Camera を使用するプロジェクトでは、リプレイする Camera を明示的に指定してください：

import { guanceSdk } from './observability';

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

setReplayCamera() は毎回1つの 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 は2つのページのルートノード、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 を設定し、離脱時に対応するルールをクリアしてください。1つのページに複数のカスタムマスクノードがある場合は、1つずつ管理する必要があります。

ページのライフサイクルでは、以下の点にも注意してください：

• ページまたは親ノードを 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/分） ≈ 平均エンコードバイト数 × 1分あたりの予定保存画像数 ÷ 1048576
全フレームの画像理論上限（MiB/分） ≈ maxFrameBytes × captureFps × 60 ÷ 1048576

繰り返し再生によるダウンロードは、画像リソース ID ごとに重複排除されます。同じ画像を再利用する複数のレコードでは、リソースサイズが重複して加算されません。集計する時間と画像コレクションは対応している必要があり、Replay 全体の画像総量をそのうちの1つの 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 のデータは 960 px のキャプチャフレームのトラフィックを表すものではありません。この表は iOS JPEG のトラフィックを推定するのには適用できず、他のシナリオの保証範囲でもありません。

Android 実機リファレンス¶

2026年9月13日、Guance Cocos 開発パッケージの Creator 2.4.9 Android サンプルの Battle シーンでは、captureFps: 3、quality: 'medium'、最長辺 720 px、1フレームあたり 40 KiB の上限を使用しました。このシーンの83枚の WebP 画像はすべて取得済みです：

この測定は 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 タイプのインポートを @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、低フレームレートのシナリオで、画像の向きとマスク位置を検証してください。