UGC 필터 규칙

Amplitude의 세션 리플레이 SDK에 있는 ugcFilterRules 기능은 Amplitude가 세션 리플레이 및 히트맵에 URL을 기록하기 전에 URL에서 민감한 사용자 생성 콘텐츠(UGC)를 감지하고 정제합니다. UGC 필터 규칙은 개인 식별 가능 정보나 민감한 정보의 캡처를 방지합니다.

UGC 필터 규칙의 기능

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

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

UGC 필터 규칙 설정

세션 리플레이 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 필터 규칙은 두 가지 필수 속성을 가진 객체입니다.

typescript

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

속성

속성	설명
`selector`	URL과 일치하는 glob 패턴 문자열.`*` (임의의 문자)를 지원합니다. 도메인과 경로에 여러 와일드카드를 지원합니다.
`replacement`	선택기 패턴이 URL과 일치할 때 SDK가 사용하는 대체 텍스트입니다.

선택기 패턴의 예제

https://*.domain.com/* 모든 하위 도메인 및 모든 경로와 일치합니다
https://site.com/*/* 두 개의 경로 세그먼트를 일치시킵니다
https://api.com/*/data/* 특정 패턴을 와일드카드로 일치시킵니다

글로브 패턴 구문

selector 필드는 URL 일치에 기본 glob 패턴을 사용합니다. 현재 구현 환경은 다음을 지원합니다.

패턴	설명	예제
`*`	모든 문자 순서와 일치합니다	`https://example.com/*` 일치 `https://example.com/anything`

지원되는 와일드카드 위치:

위치	설명	예제
여러 와일드카드	단일 패턴에서 여러 `*` 항목을 사용하십시오	`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'
}

먼저 개발 환경에서 패턴을 테스트하십시오.

글로브 패턴이 예상된 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로의 전환을 사용합니다. 이 구현은 여러 와일드카드 및 도메인 패턴을 지원하지만 고급옵션 글로브 기능을 지원하지는 않습니다. 여기에서는 가장 일반적인 URL 필터링 시나리오를 다룹니다.

이 내용이 도움이 되었나요?