データとプライバシー¶

このドキュメントでは、Cocos Creator SDK が RUM、Log、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 によってスクリーンショット内の矩形領域に投影されます。特定のセンシティブなコントロールのみを隠す必要がある場合は、そのコントロールにコンポーネントを追加し、ノードの境界を対象領域に合わせてください。

例えば、同じページに3つのセンシティブなコントロールを並べて配置し、コントロールの間と周囲に公開テキストや境界線を残す場合：

対象コントロール	設定方法	期待されるリプレイ結果
プレイヤーニックネーム	`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 は、業務側で渡された内容に応じて処理されます。デフォルトでは渡さないようにし、調査の必要がある場合は事前に脱敏とトランケーションを行ってください。

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() を使用して手動で注入範囲を制御してください。

リリース前のチェック¶

実機でログイン、決済、チャット、アカウント設定などのセンシティブなシナリオを網羅します。
RUM Resource の URL と Header を確認します。
Error Message、Stack、カスタム属性を確認します。
Console とカスタムログを確認します。
Session Replay を再生し、入力ボックスとカスタムのセンシティブ領域がマスクされていることを確認します。
Trace Header が許可されたドメインにのみ送信されていることを確認します。