URL 필터 규칙 조회
SDK가 URL을 리플레이 및 히트맵에 기록하기 전에 ugcFilterRules를 사용하여 사용자 ID나 비공개 쿼리 매개변수와 같은 민감한 URL 콘텐츠를 대체합니다. 이 참조는 규칙 구문, 순서 지정 및 유효성 검사를 설명합니다. 설치 및 테스트 단계를 위해 URL 필터링을 구성합니다.
UGC 필터 규칙의 기능
UGC 필터 규칙은 URL과 일치하는 패턴을 정의하고 대체 텍스트를 지정하는 구성 객체입니다. SDK가 세션 리플레이 및 히트맵 기록 중에 URL을 캡처할 때 SDK는 이러한 규칙을 적용하여 다음과 같은 중요한 정보를 삭제하거나 익명화합니다.
- 사용자 ID
- 회사 이름
- 민감한 쿼리 매개 변수
- 개인 데이터를 포함하는 동적 경로 세그먼트
UGC 필터 규칙 설정
독립형 SDK, 브라우저 SDK 플러그인 및 통합형 SDK의 sessionReplay옵션은 모두 interactionConfig.ugcFilterRules를 허용합니다. 각 SDK 및 개발 검사의 초기화 예제를 보려면 UGC 필터 규칙 구성으로 이동하십시오.
규칙 구조
각 UGC 필터 규칙은 두 가지 필수 속성을 가진 객체입니다.
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에서 조직 이름과 중요한 식별자를 제거하십시오.
// 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-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.