URL 필터 규칙 조회

SDK가 URL을 리플레이 및 히트맵에 기록하기 전에 ugcFilterRules를 사용하여 사용자 ID나 비공개 쿼리 매개변수와 같은 민감한 URL 콘텐츠를 대체합니다. 이 참조는 규칙 구문, 순서 지정 및 유효성 검사를 설명합니다. 설치 및 테스트 단계를 위해 URL 필터링을 구성합니다.

UGC 필터 규칙의 기능

UGC 필터 규칙은 URL과 일치하는 패턴을 정의하고 대체 텍스트를 지정하는 구성 객체입니다. SDK가 세션 리플레이 및 히트맵 기록 중에 URL을 캡처할 때 SDK는 이러한 규칙을 적용하여 다음과 같은 중요한 정보를 삭제하거나 익명화합니다.

  • 사용자 ID
  • 회사 이름
  • 민감한 쿼리 매개 변수
  • 개인 데이터를 포함하는 동적 경로 세그먼트

UGC 필터 규칙 설정

독립형 SDK, 브라우저 SDK 플러그인 및 통합형 SDK의 sessionReplay옵션은 모두 interactionConfig.ugcFilterRules를 허용합니다. 각 SDK 및 개발 검사의 초기화 예제를 보려면 UGC 필터 규칙 구성으로 이동하십시오.

규칙 구조

각 UGC 필터 규칙은 두 가지 필수 속성을 가진 객체입니다.

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

속성

선택기 패턴의 예제

  • https://*.domain.com/* 모든 하위 도메인 및 모든 경로와 일치합니다
  • https://site.com/*/* 두 개의 경로 세그먼트를 일치시킵니다
  • 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-to-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.

이 페이지에서