시작하기
이 가이드는 단 몇 분 만에 Noxtica를 웹 애플리케이션에 추가하는 데 도움이 됩니다.
사전 요구사항
- Noxtica 계정 (contact를 통해 접근 요청)
- 사이트 키 (계정 설정 후 제공됨)
빠른 통합
계정이 설정되고 사이트 키가 준비되면, HTML에 저희의 수집기를 추가하세요. 설치는 그게 전부입니다.
자동 수집 (권장)
Noxtica를 시작하는 가장 간단한 방법은 실행 한 번 모드를 사용하는 것입니다.
<script
src="https://collect.noxtica.com/collector/noxtica.js"
data-site-key="pk_prod_your_site_key_here"
data-auto-init
data-auto-check-once
async
></script>이렇게 하면:
- 첫 방문 시 방문자를 평가합니다
- 캐시 유효 기간 내 재방문에 대해 그 결과를 재사용합니다 (기본값: 7일)
- 전체 평가를 반복하지 않고 재방문을 조용히 기록합니다
- 방문자가 한 번만 평가되도록 열린 탭 간 조정합니다
결과는 다음과 같이 사용할 수 있습니다.
// Listen for results
document.addEventListener('noxtica:collected', function (e) {
console.log('Fingerprint collected:', e.detail);
console.log('Risk score:', e.detail.score);
console.log('Risk level:', e.detail.risk_level);
});
// Or access directly after collection
console.log(window.noxticaResult);수동 수집
더 세밀한 제어가 필요하다면 JavaScript API를 사용하세요.
<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
// Create a client with your Site Key
const client = NoxticaCollector.createClient({
siteKey: 'pk_prod_your_site_key_here',
});
// Collect and submit in one call
client.collectAndSubmit().then((result) => {
console.log('Risk score:', result.score);
console.log('Risk level:', result.risk_level);
console.log('Flags:', result.flags);
});
</script>checkOnce()를 사용한 스마트 수집
가장 가벼운 발자국을 위해 checkOnce()를 사용하세요. 서버에서 구성된 수집 간격을 준수하므로 필요 이상으로 자주 방문자를 재평가하지 않습니다.
const client = NoxticaCollector.createClient({
siteKey: 'pk_prod_your_site_key_here',
});
// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
const result = await client.checkOnce();
if (result.fromCache) {
console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);성능 및 사이트 영향
수집기는 페이지 로드와 사용자 체감 지연에 최소한의 영향을 미치도록 설계되었습니다.
| 지표 | 값 |
|---|---|
| 초기 스크립트 크기 | 약 167KB 축소, 약 55KB brotli |
| 수집 소요 시간 (중앙값, 첫 방문) | 최신 데스크톱에서 <50ms / 중급 스마트폰에서 <120ms |
| 위험 점수 응답까지 소요 시간 | <150ms 중앙값 (수집기 엣지 → API 엣지) |
| 캐시된 방문 (첫 로드 이후) | <10ms (핑거프린팅 작업 없음; 소형 비콘만) |
| 메인 스레드 차단 | 없음 — 수집이 비동기 청크로 실행됨 |
가볍게 유지하는 방법:
async스크립트 속성 — 수집기가 백그라운드에서 로드되며 페이지가 보이거나 인터랙티브해지는 것을 절대 지연시키지 않습니다.- 실행 한 번 모드 (
data-auto-check-once) — 첫 평가 이후 캐시 유효 기간 내 재방문은 소형 방문 핑(약 150바이트)만 전송합니다. - 탭 간 조정 — 여러 열린 탭이 단일 평가로 합쳐집니다.
- 첫 로드 후 캐시 — 변조 방지 KHAN VM이 브라우저에 캐시되어 이후 방문에서 즉시 로드됩니다.
- 백그라운드 처리 — 지원되는 환경에서 작업이 메인 스레드를 벗어나 실행되어 페이지가 반응성을 유지합니다.
SDK 추가 후 속도 저하가 느껴지면 await client.collectAndSubmit({ telemetry: true })로 프로파일을 캡처하세요. 반환된 result.telemetry에 타이밍 분석이 포함됩니다.
샌드박스 대 프로덕션
사이트 키는 두 가지: 개발 및 스테이징용 하나, 프로덕션용 하나. 각각 자체 정책에 따라 운영되며 데이터가 완전히 분리됩니다.
| 항목 | 샌드박스 (pk_sand_*) | 프로덕션 (pk_prod_*) |
|---|---|---|
| 사이트 키 접두사 | pk_sand_ | pk_prod_ |
| 출처 허용 목록 | 로컬호스트 + 스테이징 출처 | 엄격함 — 등록된 출처만 |
| 요청 한도 | 넉넉함 (약 1000/분/IP) | 플랜별 한도 적용 |
| 위험 점수 정책 | 허용적 — 최소 봇 차단 | 프로덕션 정책 적용 |
| 데이터 보존 | 7일 | 테넌트별 구성 (기본값 90일) |
| 감사 로그 보존 | 7일 | 테넌트별 구성 (기본값 90일) |
| 단계 상향 MFA | 선택 사항 | 파괴적 작업에 필수 |
항상 환경별로 사이트 키를 전환하세요. 프로덕션 트래픽에 pk_sand_* 키를 절대 사용하지 마세요. 샌드박스 데이터는 프로덕션 대시보드에 표시되지 않으며 위험 점수가 너무 관대하게 적용됩니다. 반대로 개발에 pk_prod_* 키를 사용하면 프로덕션 요청 한도 예산이 소모됩니다.
일반적인 패턴:
<script>
// Pick the key by hostname; fall back to sandbox in dev.
const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
const s = document.createElement('script');
s.src = 'https://collect.noxtica.com/collector/noxtica.js';
s.async = true;
s.dataset.siteKey = KEY;
s.dataset.autoInit = '';
s.dataset.autoCheckOnce = '';
document.head.appendChild(s);
</script>태그 매니저 호환성
수집기는 Google Tag Manager, Adobe Launch, Tealium, Segment 내에서 작동합니다. 단, 주의사항이 있습니다.
권장 (선호): HTML에 직접 스크립트를 추가하세요. </body> 바로 앞이나 <head>에 async와 함께 넣으세요. 가능한 한 일찍 시작할수록 방문자가 상호작용할 때 준비가 완료됩니다.
태그 매니저 — 작동은 하지만 주의사항:
- ✅ 대부분의 최신 태그 매니저 (GTM 커스텀 HTML, Adobe Launch 커스텀 코드, Segment 커스텀 소스)는 수집기를 성공적으로 로드합니다.
- ⚠️ 방문자가 동의를 수락할 때까지 스크립트를 차단하는 동의 게이트는 첫 평가를 지연시킵니다. 일반적으로 동의 배너가 닫힐 때까지 아무것도 실행되지 않습니다. 올바른 동작이지만 “결정까지 소요 시간” 지표에 영향을 줄 수 있습니다.
- ⚠️ 일부 구형 태그 매니저는 커스텀
data-*속성을 제거합니다.data-site-key가 스크립트 태그에 전달되지 않으면 자동 초기화가 시작되지 않습니다. 대신 코드에서 직접 설정하세요:NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce(); - ❌ 일부 무거운 샌드박스 태그 컨테이너(드문 경우)는 변조 방지 런타임 시작을 막습니다. SDK는 더 가벼운 수집 방식으로 계속 작동하며 콘솔 경고를 기록합니다.
태그 매니저를 통해 통합해야 한다면 DOM Ready 대신 All Pages — Window Loaded (또는 동등한 이벤트)에서 Noxtica 태그가 실행되도록 설정하세요. 이렇게 하면 아무것도 실행되기 전에 동의 상태가 최종 상태가 됩니다.
콘텐츠 보안 정책
사이트에서 콘텐츠 보안 정책을 사용한다면 Noxtica가 로드되고, 변조 방지 런타임(KHAN VM)을 실행하고, API와 통신할 수 있도록 허용해야 합니다. 아래 예시가 세 가지 모두를 포함합니다.
Content-Security-Policy:
default-src 'self';
script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com;
connect-src 'self' https://collect.noxtica.com;정책에서 'wasm-unsafe-eval' 토큰이 빠지면 브라우저가 변조 방지 런타임을 차단하고 관련 경고가 콘솔에 표시됩니다. Noxtica는 계속 작동하지만 더 가벼운 수집 방식으로 대체되어 변조 방지 기능이 약해집니다. 위의 토큰을 추가하면 전체 경험이 복원됩니다.
사이트 키
사이트 키(pk_...)는 귀하의 도메인에서 오는 요청을 인증하는 공개 식별자입니다. 백오피스에 추가하는 각 도메인에는 고유한 사이트 키가 발급됩니다.
중요 사항:
- 사이트 키는 공개되며 HTML에 안전하게 삽입할 수 있습니다
- 각 사이트 키는 특정 출처에 연결됩니다 (예:
https://example.com) - API는 출처가 사이트 키의 등록된 도메인과 일치하지 않는 요청을 거부합니다
구성 옵션
const client = NoxticaCollector.createClient({
// Your Site Key (required)
siteKey: 'pk_prod_your_site_key_here',
// API endpoint (defaults to production)
apiUrl: 'https://collect.noxtica.com',
// Collection mode: 'max' (default), 'standard', or 'minimal'
// Omit to use max mode (recommended)
// mode: 'standard', // Uncomment to opt out of max-only signals
});수집 모드
| 모드 | 신호 | 적합한 용도 |
|---|---|---|
minimal | 소규모 핵심 신호 세트 | 가장 빠른 수집, 최소 발자국 |
standard | 광범위한 신호 세트 | 더 가벼운 신호 세트를 선호하는 사이트 |
max | 전체 신호 세트 | 최대 정확도 (기본값) |
응답 형식
수집 및 제출 후 다음을 받습니다.
{
"success": true,
"fingerprintId": "abc123...",
"score": 15,
"risk_level": "minimal",
"confidence": 0.5,
"flags": [],
"details": {
"summary": "Detected 0 risk indicator(s)."
}
}위험 등급
| 점수 | 등급 | 의미 |
|---|---|---|
| 0-19 | minimal | 매우 낮은 위험, 정당할 가능성 높음 |
| 20-39 | low | 낮은 위험, 사소한 이상 |
| 40-59 | medium | 중간 위험, 일부 플래그 |
| 60-79 | high | 높은 위험, 자동화 가능성 |
| 80-100 | critical | 매우 높은 위험, 확인된 봇 |
인증
SDK는 사이트 키에 연결된 단기, 자동 순환 자격 증명으로 각 방문을 인증합니다. 요청하고, 새로 고침하고, 모든 제출에 첨부합니다.
이것을 직접 관리할 필요 없습니다. SDK가 자동으로 처리합니다.
온보딩 프로세스
- 접근 요청: 데모를 요청하거나 시작하려면 문의하기
- 계정 설정: 저희가 플랫폼에서 테넌트 계정을 생성합니다
- 도메인 추가: 백오피스에 로그인하고 도메인으로 이동하여 출처를 추가합니다
- 사이트 키 복사: 각 도메인에는 고유한 사이트 키가 발급됩니다
- 통합: 사이트 키가 포함된 스크립트를 페이지에 추가합니다
- 모니터링: 백오피스 대시보드에서 핑거프린트와 분석을 확인합니다
여러 도메인 관리
Noxtica는 계정당 여러 도메인을 지원합니다.
- 프로덕션:
https://www.yoursite.com - 스테이징:
https://staging.yoursite.com - 모바일:
https://m.yoursite.com
각 도메인에는 자체 사이트 키가 있습니다. 다음을 할 수 있습니다.
- 키를 재생성하지 않고 도메인을 활성화/비활성화
- 침해된 경우 사이트 키 교체
- 도메인별로 필터링된 분석 보기
SDK 버전
현재 SDK 버전: 3.3.0 (스키마: 2026-05-24)
3.3.0의 새로운 기능
- 경량 행동 신호 (항상 켜짐) — 세션 지속 시간, 방문자가 처음 상호작용하는 속도 같은 간단한 타이밍 단서. 생체 인식 데이터가 아니며 최종 사용자 동의가 필요하지 않습니다.
- 행동 생체 인식 (선택 동의) — 백오피스 → 설정 → 행동 생체 인식에서 켜면 Noxtica가 마우스 움직임의 리듬, 클릭 타이밍, 스크롤도 분석합니다. 이것은 엄격한 개인정보 보호 규정에서 생체 데이터에 해당하므로 최종 사용자의 명시적 동의가 필요합니다. 아래 행동 생체 인식을 참조하세요.
- Apple Pay 일관성 검사 — iPhone이라고 주장하는 기기가 실제로 iPhone처럼 동작하는지 확인합니다. 일반적인 위장 수법을 잡아냅니다.
- 네트워크 핑거프린트 매칭 — 일반적인 자동화 도구의 특징적인 연결 패턴을 인식합니다. 브라우저가 설득력 있게 보여도 스크립트와 봇의 트래픽이 눈에 띕니다.
- IP 평판 — 평판이 나쁜 네트워크에서 들어오는 방문자를 플래그합니다. 선호하는 위협 인텔리전스 피드를 연결하는 옵션도 있습니다.
행동 생체 인식 (선택 사항, 선택 동의)
Noxtica는 누군가가 마우스를 움직이고, 클릭하고, 스크롤하는 리듬도 분석할 수 있습니다. 기본적으로 꺼져 있는 선택 동의 기능입니다.
왜 선택 동의인가요? 이런 종류의 행동 데이터는 엄격한 개인정보 보호 규정에서 민감한 개인 데이터에 해당하므로, 최종 사용자의 명시적 동의가 필요합니다. 언제 어떻게 사용할지 제어할 수 있도록 선택 동의로 만들었습니다.
활성화하려면:
- 백오피스 → 설정 → 행동 생체 인식에 로그인합니다
- 개인정보 보호 또는 법무 팀과 함께 규정 준수 안내를 검토합니다
- 이 수집을 공개하도록 개인정보 처리방침과 동의 배너를 업데이트합니다
- 기능을 켭니다
활성화되면 Noxtica는 이후 평가에 이 행동 신호를 자동으로 반영하며, 대시보드에 도메인별 행동 점수가 표시됩니다.