データとプライバシー¶

この記事では、Cocos Creator SDK の RUM、Log、Trace、セッションリプレイで扱われる可能性のある機密データの範囲について説明します。

基本原則¶

性能と安定性の問題を特定するために必要なデータのみを収集します。
パスワード、認証コード、Token、完全な身分証明書番号、銀行カード番号などの機密情報は収集しません。
テスト環境で自動収集を有効にした場合は、実際に送信される内容を確認してから本番構成を決定してください。
カスタムタグ、ログ、手動の Resource Body のマスキングは、業務側で対応してください。

セッションリプレイ¶

デフォルトルール¶

すべての 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 を開き直し、対象ノードのコンポーネントメニューで セッションリプレイ > ReplayPrivacy を選択するか、スクリプトをインスペクターにドラッグします。
Mode を Mask（デフォルト、灰色マスク）または Hide（黒色マスク）に設定し、シーンまたはプレハブを保存します。

コンポーネントはセッションリプレイのフレームキャプチャにのみ影響し、アプリ内でリアルタイムに表示されるノードは変更されません。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 クエリ内のアカウント、Token、ビジネス ID
Authorization、Cookie、カスタム認証リクエストヘッダー
レスポンスヘッダー内のユーザーまたはテナント情報

現在の Cocos API には、URL またはヘッダーのフィルタリングコールバックはありません。ネットワークプロトコルに機密フィールドが含まれる場合は、自動ネットワーク収集をオフにし、許可されたリクエストにのみ手動の Resource と Trace API を使用してください。

自動ネットワーク収集はリクエストボディとレスポンスボディを読み取りません。手動の addResource() の responseBody はビジネス側で渡された内容がそのまま処理されるため、デフォルトでは渡さないでください。調査の必要が生じた場合は、事前にマスキングと切り詰めを行ってください。

Log と Console¶

autoTrack.console は Console の引数をテキストに変換するため、次が含まれる可能性があります。

デバッグ用 Token
完全なインターフェースオブジェクト
ユーザー入力
アカウントとデバイス識別子
例外オブジェクト内のビジネスデータ

本番環境では console: false のままにし、guanceSdk.logger.log() を使用してフィルタリング済みの内容を報告することをお勧めします。

機密オブジェクトをログの attributes に直接入れないでください。オブジェクトは JSON にシリアライズされてからログデータに含まれます。

Error¶

Error Message と Stack には次の内容が含まれる可能性があります。

URL
ファイルパス
ユーザー入力
ビジネスオブジェクトの文字列化された結果

addError() を手動で呼び出す前に、メッセージ、スタック、属性内の機密値をクリーンアップしてください。自動エラー監視ではマスキング用のコールバックを提供できません。アプリケーションの例外内容を制御できない場合は、autoTrack.errors をオフにし、ビジネスのエラーバウンダリでマスキングした後に手動で報告してください。

ユーザーとカスタムタグ¶

userId には、内部の不可逆な識別子を使用することをお勧めします。携帯電話番号やメールアドレスを ID として使用しないでください。
userEmail は、ビジネス上で本当に必要な場合にのみ渡してください。
extra とすべての globalContext には、機密性が低く、安定しており、フィルタリングに使用できるタグのみを追加してください。
高カーディナリティのフィールドや、リクエストごとに変化する内容をグローバルタグに設定しないでください。

Trace ヘッダー¶

Trace ヘッダーは、信頼できるビジネスドメインにのみインジェクションしてください。サードパーティのドメインが Trace 識別子を受信すると、内部のトレーシング関係が露呈する可能性があります。自動ネットワークトレーシングでドメインごとのフィルタリングができない場合は、trace.getHeaders() に切り替えて、インジェクション範囲を手動で制御してください。

公開前の確認¶

実機でログイン、決済、チャット、アカウント設定などの機密シナリオを一通り確認します。
RUM Resource の URL とヘッダーを確認します。
Error Message、Stack、カスタム属性を確認します。
Console とカスタムログを確認します。
セッションリプレイを再生し、入力欄とカスタムの機密領域がマスクされていることを確認します。
Trace ヘッダーが許可されたドメインにのみ送信されることを確認します。