URLフィルタルールを検索

SDKがURLをリプレイやヒートマップに記録する前に、ユーザーIDやプライベートクエリパラメータなどの機密性の高いURLコンテンツを置き換えるためにugcFilterRulesを使用します。このリファレンスでは、ルールの構文、順序付け、および検証について説明します。 インストールとテストの手順については、URLフィルタリングを設定します。

UGCフィルタルールの機能

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

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

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

Standalone SDK、Browser SDKプラグイン、およびUnified SDKのsessionReplayオプションはすべて、interactionConfig.ugcFilterRulesを受け入れます。各SDKの初期化例と開発チェックについては、「UGCフィルタールールの設定」を参照してください。

ルール構造

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

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

プロパティ

セレクターパターンの例

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

グロブパターン構文

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

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

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フィルタルールを検証します。

検証ルール

エラーの例

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'
}

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

確認するURLについては、まず開発環境でのテストパターンに移動します。

一般的な問題

制限事項

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

SDKは、複数のワイルドカードとドメインパターンをサポートする単純なglobからregexへのコンバージョンを使用します。

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

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

このページでは