Look up URL filter rules

Use ugcFilterRules to replace sensitive URL content, such as user IDs or private query parameters, before the SDK records URLs in replays and heatmaps. This reference explains rule syntax, ordering, and validation. For installation and testing steps, configure URL filtering.

What UGC Filter Rules do

UGC Filter Rules are configuration objects that define patterns to match URLs and specify replacement text. When the SDK captures URLs during session replay and heatmap recording, the SDK applies these rules to sanitize or anonymize sensitive information such as:

User IDs
Company names
Sensitive query parameters
Dynamic path segments containing private data

Configure UGC Filter Rules

For SDK initialization and development checks, go to Configure UGC Filter Rules.

Rule structure

Each UGC Filter Rule is an object with two required properties:

typescript

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

Properties

Property	Description
`selector`	A glob pattern string that matches URLs. Supports `*` (any characters). Supports multiple wildcards in domains and paths.
`replacement`	The replacement text that the SDK uses when the selector pattern matches a URL.

Selector pattern examples

https://*.domain.com/* matches any subdomain and any path.
https://site.com/*/* matches two path segments.
https://api.com/*/data/* matches specific patterns with wildcards.

Glob pattern syntax

The selector field uses basic glob patterns for URL matching. The current implementation supports:

Pattern	Description	Example
`*`	Matches any sequence of characters	`https://example.com/*` matches `https://example.com/anything`

Supported wildcard locations:

Location	Description	Example
Multiple wildcards	Use multiple `*` in a single pattern	`https://.domain.com//*`
Domain wildcards	`*` works in domain names	`*.projecttool.com`
Path wildcards	Multiple `*` in URL paths	`/projects//boards/`

The SDK doesn't support advanced glob features such as **, [abc], {option1,option2}, and others.

Examples

Filter project management tool URLs

Remove organization names and sensitive identifiers from project management URLs:

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

Filter code repository URLs

Remove repository details and sensitive paths:

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

Filter user IDs from profile URLs

Remove user IDs from profile URLs:

javascript

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

Before: https://myapp.com/user/12345/profile
After: https://myapp.com/user/USER_ID/profile

Sanitize query parameters

Remove sensitive query parameters:

javascript

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

Before: https://myapp.com/dashboard?token=abc123xyz
After: https://myapp.com/dashboard?token=REDACTED

Filter URLs with multiple path segments

Filter URLs with multiple dynamic segments:

javascript

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

Before: https://api.example.com/users/john123/documents/private/contract-2023.pdf
After: https://api.example.com/users/USER_ID/documents/CATEGORY/DOCUMENT_ID

Filter email addresses in URLs

Remove email addresses from URL paths:

javascript

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

Before: https://myapp.com/user/john.doe@company.com/settings
After: https://myapp.com/user/EMAIL_ADDRESS/settings

Advanced usage

Rule precedence with multiple rules

The SDK applies rules in order, and the first matching rule wins:

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",
  },
];

Complete configuration example

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",
      },
    ],
  },
});

Error handling and validation

The SDK validates UGC Filter Rules during initialization.

Validation rules

Rule	Requirement
Type validation	Both `selector` and `replacement` must be strings.
URL format validation	The `selector` must be a valid URL pattern that starts with `/`, `http://`, or `https://`.
Non-empty	Selectors can't be empty or whitespace-only.

Error examples

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

Best practices

Order rules by specificity

Place more specific patterns before general ones:

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",
  },
];

Use descriptive replacements

Make replacements clear and meaningful:

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

Test patterns in a development environment first

Go to Test patterns in a development environment first for example URLs to check.

Common issues

Issue	Resolution
Rules not applied	Ensure `interactionConfig.enabled` is `true`.
Pattern not matching	Use only `*` patterns.
Wrong order	Check that specific rules come before general ones.
Invalid patterns	Verify that selectors only use supported glob syntax (`*`).

Limitations

The SDK applies rules to full URLs, not individual URL components.
The SDK supports only * (any characters) for glob patterns.
The SDK doesn't support advanced glob features such as **, [abc], {option1,option2}, ranges, and negation.
Rules can't modify URL structure. Rules can only replace entire URLs.

The SDK uses a simple glob-to-regex conversion that supports multiple wildcards and domain patterns.

Was this helpful?