🔎

facejs

브라우저 환경 정보를 조합해 고유한 fingerprint 를 생성하는
경량 JavaScript SDK

v1.2.2 Browser Fingerprint Agent

facejs 란?

facejs 는 웹 브라우저가 노출하는 다양한 환경 정보 — Canvas 렌더링, WebGL 파라미터, Audio Context, 설치 폰트, 화면 해상도, 타임존 등 — 를 수집·해시하여 사용자별 고유 식별값(BrowserEnvKey) 을 생성합니다. 쿠키에 의존하지 않으므로 시크릿 모드, 쿠키 삭제 환경에서도 동일 사용자를 추적할 수 있습니다.

수집된 시그널은 RSA-OAEP(v4) 또는 Basic auth(v3) 프로토콜로 암호화 전송되며, 서버에서 Proxy / VPN / Bot / Suspect 등 위험 스코어를 산출해 반환합니다. 총 60+ 프로토콜에 걸쳐 브라우저 핑거프린트, 환경 플래그, 위험 지표를 제공합니다.

🔒

RSA-OAEP 암호화

v4 프로토콜: 서버 공개키로 AES 세션키를 암호화하는 비대칭 핸드셰이크. 키 노출 없는 안전한 전송.

🎨

Canvas / WebGL / Audio

GPU·오디오 렌더링 결과를 해시하여 높은 엔트로피의 브라우저 고유값을 추출합니다.

🛡

Anti-Fraud 스코어

Proxy · VPN · Bot · Suspect 종합 점수와 VM · Incognito · Headless 탐지 플래그를 반환합니다.

🔌

경량 & 무의존

CDN script 태그 한 줄로 연동. npm 불필요. 번들 크기 최소화. IE11 호환 빌드 지원.

🛠

BrowserEnvKey 분석

60+ 시그널의 엔트로피·안정성을 시각화. 커스텀 프리셋으로 수집 항목 조절 가능.

📡

Canvas 변조 탐지

CanvasBlocker · Brave farbling 등 픽셀 노이즈 주입을 3회 draw 비교로 자동 감지합니다.

동작 흐름

script 로딩

CDN 또는 self-hosted 로
face-bundle.min.js 삽입

→

시그널 수집

Canvas · WebGL · Audio 등
60+ 브라우저 환경 정보 수집

→

암호화 전송

RSA-OAEP(v4) 핸드셰이크로
Face 서버에 안전하게 전송

→

결과 반환

BrowserEnvKey + Risk Score
콜백으로 수신

Quick Start

<!-- 1. 스크립트 삽입 -->
<script src="https://your-cdn/facejs/dist/face.config.js"></script>
<script src="https://your-cdn/facejs/dist/face-compatible.min.js"></script>

<!-- 2. 수집 실행 -->
<script>
  FaceJS.load(5000).then(function(result) {
    console.log(result.uuidKey);      // 사용자 식별키
    console.log(result.data);         // 암호화된 수집 데이터
    console.log(result.resultCode);   // "success" | "timeout" | "error"
    console.log(result.duration);     // 수집 소요시간 (ms)
  });
</script>

ⓘ face.config.js 를 face-compatible.min.js 보다 먼저 로드해야 합니다. config 의 url, packetVersion 을 환경에 맞게 설정하세요.

face.config.js 설정

facejs 는 전역 변수 faceConfig 로 동작을 제어합니다. face.config.js 파일에 아래 형식으로 선언하면 SDK 가 자동으로 읽어갑니다.

var faceConfig = {
  packetVersion: 4,              // 프로토콜 버전 (3: Basic auth, 4: RSA-OAEP)
  logLevel:       "error",        // "error" | "info" | "debug"
  siteId:         "",             // 사이트 구분 ID (서버 설정과 매칭)
  url:            "https://face-server.example.com?timeout=3000",
  dataStore: {
    cookie:       { use: true, cookieExpire: 365, sameSite: "lax" },
    localStorage: { use: true },
    indexedDB:    { use: true, database: "faceDatabase", tableName: "faceTable" }
  },
  keyName:     "73976c5b790b466791bd62b66cd9982b",   // uuidKey 쿠키/저장소 키 이름
  keyMetaName: "34d589d9f4bf462292977a19f9e21781",   // 서버 실패 시 로컬 키 복원용
  iceServers:  [],                              // STUN 서버 목록 (비어있으면 공용 폴백)
  iceServersTimeout: 2000                       // WebRTC STUN 타임아웃 (ms)
};

옵션	타입	기본값	설명
`packetVersion`	number	`3`	프로토콜 버전. `3` = Basic auth 방식, `4` = RSA-OAEP 비대칭 핸드셰이크 (권장)
`url`	string	`http://127.0.0.1:4443?timeout=1000`	Face 수집 서버 URL. `?timeout=` 쿼리로 서버 응답 대기 시간(ms) 지정
`logLevel`	string	`"error"`	콘솔 로그 레벨. `"error"` / `"info"` / `"debug"` (debug 시 browserMap 전체 출력)
`siteId`	string	`""`	다수 사이트 운영 시 구분 ID. 서버 측 siteId 설정과 일치시켜야 함
`dataStore.cookie`	object	`{ use: true, cookieExpire: 365, sameSite: "lax" }`	쿠키 저장소 설정. `use: false` 로 비활성화 가능. `cookieExpire`: 만료 일수, `sameSite`: strict/lax/none
`dataStore.localStorage`	object	`{ use: true }`	localStorage 저장소 사용 여부
`dataStore.indexedDB`	object	`{ use: true, database: "faceDatabase", tableName: "faceTable" }`	IndexedDB 저장소 설정. DB/테이블 이름 커스터마이징 가능
`keyName`	string	`"73976c..."`	uuidKey 를 저장하는 쿠키/localStorage 키 이름. 사이트별로 변경 가능
`keyMetaName`	string	`"34d589..."`	서버 응답 실패 시 로컬에서 키를 복원하기 위한 메타 키 이름
`iceServers`	string[]	`[]`	WebRTC STUN 서버 URL 목록. 비어있으면 Google/Cloudflare 공용 STUN 사용
`iceServersTimeout`	number	`2000`	STUN 서버 응답 타임아웃 (ms)

반환 결과 (ResultSpec) — FaceJS.load() 가 resolve 하는 객체:

필드	타입	설명
`uuidKey`	string	사용자 고유 식별키 (서버 발급, 쿠키/localStorage/IndexedDB에 영속)
`data`	string	암호화된 수집 데이터 패킷 (서버 전송용)
`simpleData`	string	경량 패킷 (선택적)
`resultCode`	string	`"success"` / `"timeout"` / `"error"`
`resultMessage`	string	결과 메시지 (에러 시 상세 내용)
`duration`	number	수집 소요 시간 (ms)
`rawData`	object	암호화 전 원본 프로토콜 → 값 매핑 (디버깅용, 운영 환경 비노출 권장)

주요 프로토콜 요약

범위	카테고리	주요 항목
`101–116`	브라우저 기본	userAgent, vendor, cookieEnabled, language …
`201–208`	OS / 환경	platform, timezone, fonts, UA-CH 불일치, 폰트-언어 불일치
`301–315`	화면 / 디스플레이	screen width/height, devicePixelRatio
`501–511`	네트워크 / 위험 스코어	natIp, Tor 탐지, Proxy/VPN/Suspect Score & Level
`601–614`	식별키 / 렌더링	uuidKey, BrowserEnvKey, Canvas hash, Canvas 랜덤화(608), GPU
`700–716`	Anti-Fraud	Headless, webdriver, Bot Score, VM, Incognito, UA Client Hints
`777–797`	고급 핑거프린트	WebGL hash, Audio hash, Geometry, Math, CSS Media, Permissions …