UGCフィルタルール

AmplitudeのSession Replay SDKに含まれるugcFilterRules機能は、AmplitudeがセッションリプレイやヒートマップにURLを記録する前に、URL内の機密性の高いユーザー生成コンテンツ（UGC）を検出してサニタイズします。UGCフィルタルールは、個人を特定できる情報や機密情報の取得を防止します。

UGCフィルタルールの機能

UGCフィルタルールは、URLに一致するパターンを定義し、置換テキストを指定する設定オブジェクトです。セッションリプレイやヒートマップの記録中にSDKがURLをキャプチャするとき、SDKはこれらのルールを適用して、以下のような機密情報をサニタイズまたは匿名化します。

ユーザーID
会社名
機密性の高いクエリパラメータ
プライベートデータを含む動的パスセグメント

UGCフィルタルールを設定する

Session Replay SDKを初期化するときにinteractionConfigの一部としてUGCフィルタルールを設定します。

javascript

import { sessionReplay } from '@amplitude/session-replay-browser';
sessionReplay.init('YOUR_API_KEY', {
    // ...
    // Other Configs
    // ...
  interactionConfig: {
    enabled: true,
    ugcFilterRules: [
      {
        selector: 'https://example.com/user/*/profile',
        replacement: 'https://example.com/user/USER_ID/profile'
      },
      {
        selector: 'https://example.com/api/token=*',
        replacement: 'https://example.com/api/token=REDACTED'
      }
    ]
  }
});

ルール構造

各 UGC フィルタルールは、2 つの必須プロパティを持つオブジェクトです。

typescript

type UGCFilterRule = {
  selector: string;    // Glob pattern to match URLs
  replacement: string; // Text to replace the matched URL
};

プロパティ

プロパティ	概要
`selector`	URLと一致するグロブパターン文字列。`*`（任意の文字）をサポートします。ドメインとパスで複数のワイルドカードをサポートしています。
`replacement`	セレクターパターンが URL と一致した場合に SDK が使用する置換テキストです。

セレクターパターンの例

https://*.domain.com/* 任意のサブドメインとパスに一致します
https://site.com/*/* 2つのパスセグメントを一致させる
https://api.com/*/data/* 特定のパターンをワイルドカードで照合する

グロブパターン構文

このselectorフィールドは、URL照合に基本的なglobパターンを使用します。現在の実装は以下をサポートしています：

パターン	概要	例
`*`	任意の文字列と一致	`https://example.com/*`と`https://example.com/anything`は一致します

サポートされているワイルドカードの場所：

所在地	概要	例
複数のワイルドカード	1つのパターンで複数の`*`を指定します	`https://.domain.com//*`
ドメインワイルドカード	`*`はドメイン名で機能します	`*.projecttool.com`
パスのワイルドカード	URLパス内の複数の`*`	`/projects//boards/`

SDKは、**、[abc]、{option1,option2}などの高度なglob機能には対応していません。

例

プロジェクト管理ツールの URL をフィルタリングする

プロジェクト管理URLから組織名と機密識別子を削除します。

javascript

// Filter ticket URLs
{
  selector: "https://*.projecttool.com/browse/*",
  replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER"
}
// Filter project list URLs  
{
  selector: "https://*.projecttool.com/software/projects/*/list*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/list"
}
// Filter board URLs
{
  selector: "https://*.projecttool.com/software/projects/*/boards/*",
  replacement: "https://ORG_NAME.projecttool.com/software/projects/boards/BOARD_ID"
}
// Filter wiki pages
{
  selector: "https://*.projecttool.com/wiki/spaces/*/pages/*",
  replacement: "https://ORG_NAME.projecttool.com/wiki/spaces/SPACE_NAME/pages/PAGE_NAME"
}

コードリポジトリの URL をフィルタリングする

リポジトリの詳細と機密パスを削除します。

javascript

// Filter repository file browser with branch and file paths
{
  selector: "https://codehost.com/*/*/tree/*/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES"
}
// Filter repository branch view
{
  selector: "https://codehost.com/*/*/tree/*",
  replacement: "https://codehost.com/USER/REPO/tree/BRANCH"
}

プロファイルURLからユーザーIDをフィルタリングする

プロファイルURLからユーザーIDを削除します：

javascript

{
  selector: 'https://myapp.com/user/*/profile',
  replacement: 'https://myapp.com/user/USER_ID/profile'
}

以前: https://myapp.com/user/12345/profile
その後: https://myapp.com/user/USER_ID/profile

クエリパラメータをサニタイズする

機密性の高いクエリパラメータを削除します。

javascript

{
  selector: 'https://myapp.com/dashboard?token=*',
  replacement: 'https://myapp.com/dashboard?token=REDACTED'
}

以前: https://myapp.com/dashboard?token=abc123xyz
その後: https://myapp.com/dashboard?token=REDACTED

複数のパスセグメントを含むURLをフィルタリングする

複数の動的セグメントを含むURLをフィルタリングします。

javascript

{
  selector: 'https://api.example.com/users/*/documents/*/*',
  replacement: 'https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID'
}

以前: https://api.example.com/users/john123/documents/private/contract-2023.pdf
その後: https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID

URL内のメールアドレスをフィルタリングする

URL パスから電子メールアドレスを削除します。

javascript

{
  selector: 'https://myapp.com/user/*/settings',
  replacement: 'https://myapp.com/user/EMAIL_ADDRESS/settings'
}

以前: https://myapp.com/user/john.doe@company.com/settings
その後: https://myapp.com/user/EMAIL_ADDRESS/settings

高度な使い方

複数のルールがある場合のルールの優先順位

SDKはルールを順番に適用し、最初に一致するルールが優先されます。

javascript

ugcFilterRules: [
  // More specific rule - will match first
  {
    selector: 'https://example.com/user/*/profile/settings',
    replacement: 'https://example.com/user/USER_ID/profile/settings'
  },
  // Less specific rule - will only match if first rule doesn't
  {
    selector: 'https://example.com/user/*/*',
    replacement: 'https://example.com/user/USER_ID/ACTION'
  }
]

完全な設定例

javascript

import { sessionReplay } from '@amplitude/session-replay-browser';
sessionReplay.init('YOUR_API_KEY', {
  interactionConfig: {
    enabled: true,
    ugcFilterRules: [
      // Filter project management tool URLs
      {
        selector: "https://*.projecttool.com/browse/*",
        replacement: "https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER"
      },
      {
        selector: "https://*.projecttool.com/software/projects/*/boards/*",
        replacement: "https://ORG_NAME.projecttool.com/software/projects/PROJECT_NAME/boards/BOARD_ID"
      },
      
      // Filter code repository URLs
      {
        selector: "https://codehost.com/*/*/tree/*/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH/FILES"
      },
      {
        selector: "https://codehost.com/*/*/tree/*",
        replacement: "https://codehost.com/USER/REPO/tree/BRANCH"
      },
      
      // Filter internal application URLs
      {
        selector: 'https://myapp.com/user/*/profile',
        replacement: 'https://myapp.com/user/USER_ID/profile'
      },
      {
        selector: 'https://api.myapp.com/*?token=*',
        replacement: 'https://api.myapp.com/ENDPOINT?token=REDACTED'
      },
      
      // Filter admin URLs completely
      {
        selector: 'https://myapp.com/admin/*',
        replacement: 'https://myapp.com/admin/ADMIN_SECTION'
      }
    ]
  }
});

エラー処理と検証

SDKは初期化時にUGCフィルタルールを検証します。

検証ルール

ルール	要件
タイプ検証	`selector`と`replacement`は両方とも文字列である必要があります。
URL形式の検証	`selector`は、`/`、`http://`、または`https://`で始まる有効なURLパターンである必要があります。
空でない	セレクターを空にする、または空白のみにすることはできません。

エラーの例

javascript

// ❌ Invalid - non-string selector
{
  selector: 123,
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties
// ❌ Invalid - non-string replacement
{
  selector: 'https://example.com/*',
  replacement: 456
}
// Error: ugcFilterRules must be an array of objects with selector and replacement properties
// ❌ Invalid - selector doesn't start with / or http(s)://
{
  selector: 'example.com/path',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs
// ❌ Invalid - empty selector
{
  selector: '',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs
// ❌ Invalid - whitespace-only selector
{
  selector: '   ',
  replacement: 'replacement'
}
// Error: ugcFilterRules must be an array of objects with valid globs

ベストプラクティス

特定性によるルールの順序付け

一般的なパターンの前に、より具体的なパターンを配置してください：

javascript

ugcFilterRules: [
  // More specific patterns first
  {
    selector: 'https://codehost.com/*/*/tree/*/*',
    replacement: 'https://codehost.com/USER/REPO/tree/BRANCH/FILES'
  },
  // Less specific patterns later
  {
    selector: 'https://codehost.com/*/*/tree/*',
    replacement: 'https://codehost.com/USER/REPO/tree/BRANCH'
  },
  // Most general patterns last
  {
    selector: 'https://codehost.com/*/*',
    replacement: 'https://codehost.com/USER/REPO'
  }
]

説明的な置換を使用する

置換を明確かつ有意義なものにしましょう：

javascript

// ✅ Good - descriptive
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://ORG_NAME.projecttool.com/browse/TICKET_NUMBER'
}
// ❌ Avoid - unclear
{
  selector: 'https://*.projecttool.com/browse/*',
  replacement: 'https://XXX.projecttool.com/browse/XXX'
}

まず開発環境でのパターン検証

globパターンが予想されるURLと一致することを検証します。

javascript

// Test with various URL formats
const testUrls = [
  'https://mycompany.projecttool.com/browse/PROJ-123',
  'https://codehost.com/username/repository/tree/main/src/components',
  'https://myapp.com/user/john.doe@email.com/profile'
];

一般的な問題

問題点	解決策
ルールが適用されていません	`interactionConfig.enabled`が `true` であることを確認してください。
パターンが一致しません	サポートされているのは`*`パターンのみです。
間違った順序	特定のルールが一般ルールよりも先に来ることを確認してください。
無効なパターン	セレクタがサポートされているglob構文のみを使用していることを確認してください（`*`）。

制限事項

SDKはルールを個々のURLコンポーネントではなく、URL全体に適用します。
制限付きglobパターンのサポート：*（任意の文字）のみがサポートされます。
SDKは**、[abc]、{option1,option2}、範囲や否定など、高度なglob機能をサポートしていません。
ルールではURL構造を変更できません。ルールは、URL全体のみを置き換えることができます。

現在の実装では、単純なglobからregexへの変換を使用しています。この実装では複数のワイルドカードとドメインパターンがサポートされていますが、高度なglob機能はサポートされていません。ここでは、URLフィルタリングの最も一般的なシナリオについて説明します。

これは役に立ちましたか？

UGCフィルタルール

UGCフィルタルールの機能

UGCフィルタルールを設定する

ルール構造

プロパティ

セレクターパターンの例

グロブパターン構文

例

プロジェクト管理ツールの URL をフィルタリングする

コード リポジトリの URL をフィルタリングする

プロファイルURLからユーザーIDをフィルタリングする

クエリパラメータをサニタイズする

複数のパスセグメントを含むURLをフィルタリングする

URL内のメールアドレスをフィルタリングする

高度な使い方

複数のルールがある場合のルールの優先順位

完全な設定例

エラー処理と検証

検証ルール

エラーの例

ベストプラクティス

特定性によるルールの順序付け

説明的な置換を使用する

まず開発環境でのパターン検証

一般的な問題

制限事項

コードリポジトリの URL をフィルタリングする