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 つの必須プロパティを持つオブジェクトです。
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から組織名と機密識別子を削除します。
// 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 をフィルタリングする
リポジトリの詳細と機密パスを削除します。
// 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を削除します:
{
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
クエリパラメータをサニタイズする
機密性の高いクエリパラメータを削除します。
{
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をフィルタリングします。
{
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 パスから電子メールアドレスを削除します。
{
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はルールを順番に適用し、最初に一致するルールが優先されます。
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",
},
];
完全な設定例
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パターンである必要があります。 |
| 空でない | セレクターを空白のみにすることはできません。 |
エラーの例
// ❌ 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
ベストプラクティス
特定性によるルールの順序付け
一般的なパターンの前に、より具体的なパターンを配置してください:
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",
},
];
説明的な置換を使用する
置換を明確かつ有意義なものにしましょう:
// ✅ 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については、まず開発環境でのテストパターンに移動します。
一般的な問題
| 問題点 | 解決策 |
|---|---|
| ルールが適用されていません | interactionConfig.enabledが true であることを確認してください。 |
| パターンが一致しません | パターンのみ*を使用してください。 |
| 間違った順序 | 特定のルールが一般ルールよりも先に来ることを確認してください。 |
| 無効なパターン | セレクタがサポートされているglob構文のみを使用していることを確認してください(*)。 |
制限事項
- 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.