브라우저 런타임

이 가이드는 Noxtica SDK가 방문자의 브라우저 내에서 어떻게 작동하는지, 평가 중에 무슨 일이 일어나는지, 캐싱이 속도를 어떻게 유지하는지, 그리고 일반적인 문제를 해결하는 방법을 설명합니다.

작동 방식

페이지에 Noxtica SDK를 추가하면 네 가지 작업이 조용히 실행됩니다.

1. 인증: 자동으로 관리되는 자격 증명으로 사이트 키를 사용해 로그인합니다
2. 수집: 브라우저가 이미 노출하는 일상적인 신호를 읽습니다
3. 제출: 점수 산정을 위해 Noxtica로 전송합니다
4. 캐시: 모든 방문마다 작업을 반복하지 않도록 결과를 로컬에 저장합니다

이 모든 것이 백그라운드에서 실행되며 페이지를 절대 차단하지 않습니다.

수집 흐름

자동 (권장)

data-auto-check-once를 사용할 때 SDK는 스마트 수집을 사용합니다.

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key"
	data-auto-init
	data-auto-check-once
	async
></script>

콘텐츠 보안 정책을 사용 중이신가요? Noxtica가 변조 방지 런타임인 KHAN VM을 로드하고 실행할 수 있도록 허용해야 합니다. 허용하지 않으면 Noxtica는 더 가벼운 수집 방식으로 계속 작동하지만 변조 방지 기능이 약해집니다. 정확한 스니펫은 **시작하기 → 콘텐츠 보안 정책**을 참조하세요.

첫 방문: 전체 평가가 실행되고 결과가 캐시됩니다.

캐시 유효 기간 내 재방문: 캐시된 결과가 반환되고 가벼운 방문이 기록됩니다. 무거운 작업은 실행되지 않습니다.

캐시 유효 기간 만료 후: 새로운 평가가 실행됩니다.

수동 제어

프로그래밍 방식 제어를 위해 checkOnce() 메서드를 사용하세요.

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key',
});

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

캐싱 동작

SDK는 동일한 방문자를 모든 페이지 뷰마다 재평가하지 않도록 각 결과를 브라우저에 캐시합니다.

캐시 키

nox_fp_{your_site_key}

캐시되는 항목

• 기기 ID
• 마지막 제출 타임스탬프
• 마지막 확인 타임스탬프
• 이전 위험 점수 및 등급

TTL (유효 기간)

기본 캐시 TTL은 7일입니다. 구성할 수 있습니다.

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

강제 새로고침

캐시를 우회하고 새로운 핑거프린트를 수집하려면:

const result = await client.checkOnce({
	forceRefresh: true,
});

탭 간 조정

방문자가 사이트의 여러 탭을 동시에 열면 SDK는 한 번만 평가되도록 보장합니다.

• 하나의 탭만 실제 작업을 수행합니다
• 다른 탭은 대기하다가 결과를 공유합니다

이는 자동으로 처리됩니다 — 별도 설정이 필요 없습니다.

이벤트

SDK는 청취할 수 있는 이벤트를 발생시킵니다.

noxtica:collected

성공적인 수집 후 또는 캐시된 결과를 반환할 때 발생합니다.

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

캐시된 결과가 반환될 때 특별히 발생합니다.

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

수집이 실패할 때 발생합니다.

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

전역 변수

수집 후 결과를 전역으로 사용할 수 있습니다.

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

오류 처리

일반적인 오류

오류를 직접 처리하기

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

수집 모드

SDK는 세 가지 수집 모드를 지원합니다.

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // or 'minimal', 'standard'
});

보호 모드 (KHAN VM)

봇과 싸우는 데 가장 어려운 부분은 브라우저에서 실행되는 모든 것이 원칙적으로 보이고 편집 가능하다는 것입니다. 의지 있는 공격자는 페이지 코드를 읽어 무엇이 측정되는지 파악하고, 조용히 가짜 답변을 돌려줄 수 있습니다.

KHAN VM은 그 비용을 높입니다. 수집을 페이지에서 읽기 쉬운 코드로 노출하는 대신, Noxtica는 민감한 부분을 봉인된 샌드박스 런타임 내부에서 실행합니다. 무엇을 측정할지 결정하는 로직이 공격자가 연구하고 재작성할 수 있도록 공개되어 있지 않으며, 생성된 결과는 브라우저를 떠나기 전에 봉인됩니다. 변조하거나 재사용하기가 훨씬 어렵습니다.

KHAN VM이 도움이 되는 것:

• 변조 방지 결과 — 평가는 샌드박스 내부에 봉인된 후 전송됩니다. 페이지의 다른 스크립트가 조용히 변경하거나 재사용할 수 없습니다.
• 역공학하기 어려움 — 수집 로직이 브라우저 개발자 도구에서 읽히는 대신 런타임 내부에 숨겨져 있습니다.
• 재사용 방지 — 각 결과는 일회용으로 검증되므로, 캡처된 응답을 깨끗한 방문자로 위장하는 데 재사용할 수 없습니다.

솔직한 한계 — 하지 않는 것:

• 이것은 변조 방지 기능이지 종단간 암호화가 아닙니다.
• 페이지 자체가 침해된 경우(예: 크로스 사이트 스크립팅 취약점), 페이지의 공격자는 Noxtica가 보는 것과 동일한 원시 브라우저 신호를 볼 수 있습니다. KHAN VM은 처리 과정과 결과를 보호하지, 그 주변 페이지를 보호하지 않습니다.

KHAN VM은 서버 측에서 켜지며 통합에 변경이 필요 없습니다. 시작할 수 없는 경우—예를 들어 콘텐츠 보안 정책이 차단하는 경우—Noxtica는 더 가벼운 수집 방식으로 대체되어 탐지가 계속 작동합니다. 다만 변조 방지 기능이 약해집니다.

브라우저 지원

SDK는 최신 브라우저를 지원합니다.

이전 브라우저는 신호 정확도가 감소할 수 있지만 여전히 작동합니다.

디버그 모드

문제 해결을 위해 디버그 로깅을 활성화하세요.

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

디버그 모드는 다음을 기록합니다.

• 수집 진행 상황
• 토큰 수명 주기
• 캐시 히트 및 미스
• 발생한 오류

참고: 디버그 모드는 프로덕션에서 기본적으로 출력이 없습니다. 명시적으로 활성화하지 않는 한 콘솔 출력이 나타나지 않습니다.

저장소 고려사항

브라우저 저장소

SDK는 결과를 캐시하기 위해 브라우저의 로컬 저장소를 사용합니다. 사용할 수 없는 경우(예: 시크릿 브라우징 또는 저장소 비활성화):

• 탐지는 계속 작동합니다
• 모든 페이지 로드마다 새로운 평가가 실행됩니다
• 탭 간 조정이 줄어들 수 있습니다

쿠키 없음

SDK는 쿠키를 사용하지 않습니다. 필요한 모든 것은 브라우저의 로컬 저장소에 보관됩니다.

성능 영향

첫 방문

수집은 비동기적으로 실행되며 페이지 렌더링을 차단하지 않습니다.

재방문 (캐시 히트)

문제 해결

핑거프린트가 수집되지 않음

1. 브라우저 콘솔에서 오류를 확인하세요
2. 사이트 키가 도메인과 정확히 일치하는지 확인하세요 (https:// 포함)
3. 도메인이 백오피스에서 활성화되어 있는지 확인하세요
4. 자세한 로그를 보려면 디버그 모드를 활성화하세요

”WebAssembly blocked by Content Security Policy”

브라우저 콘솔에서 이 경고가 표시되면 페이지의 콘텐츠 보안 정책이 변조 방지 런타임(KHAN VM)을 차단하고 있는 것입니다. 탐지는 더 가벼운 모드로 계속 작동하지만, 허용하면 가장 강력한 보호를 받을 수 있습니다.

아래 스니펫을 사용해 Noxtica가 로드되고 실행될 수 있도록 허용하세요.

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com; connect-src 'self' https://collect.noxtica.com

전체 참조는 시작하기 → 콘텐츠 보안 정책을 참조하세요.

동일한 기기에서 다른 기기 ID

다음과 같은 경우에 발생할 수 있습니다.

• 브라우저에 저장된 데이터가 지워진 경우
• 브라우저 프로필이 변경된 경우
• 시크릿/프라이빗 모드 사용
• 브라우저가 주요 업데이트를 받은 경우

이는 예상되는 동작입니다 — 인식 기능이 기기 변화에 따라 적응합니다.

수집에 너무 오래 걸림

1. 느린 API 응답에 대해 네트워크 탭을 확인하세요
2. 더 빠른 수집을 위해 mode: 'minimal' 사용을 고려하세요
3. SDK가 async 속성으로 로드되었는지 확인하세요

이벤트가 발생하지 않음

1. SDK가 실행되기 전에 청취하고 있는지 확인하세요
2. 자동 초기화 속성이 올바른지 확인하세요
3. 실행을 차단하는 JavaScript 오류가 없는지 확인하세요

모범 사례

1. 중복 수집을 최소화하기 위해 data-auto-collect 대신 data-auto-check-once를 사용하세요

2. 페이지 로드 차단을 피하기 위해 async 속성으로 SDK를 비동기적으로 로드하세요

3. window.noxticaResult를 폴링하는 대신 이벤트를 청취하세요

4. TTL을 불필요하게 재정의하지 마세요 — 기본 7일 간격은 대부분의 사용 사례에 최적화되어 있습니다

5. 오류를 우아하게 처리하세요 — 수집 실패가 페이지를 망가뜨려서는 안 됩니다

다음 단계

• 시작하기 — 초기 설정 가이드
• 백엔드 통합 — 서버 측 기기 조회