프로젝트 소개

Tracker SDK는 모던 웹 애플리케이션, 특히 Vibe Coding 같은 AI 지원 도구로 생성된 애플리케이션에 빠른 통합을 위해 설계된 경량 웹 분석 라이브러리입니다. 단순함을 중시하며, 단일 `init` 호출만으로 수집기 엔드포인트를 설정하면 페이지뷰가 자동으로 기록되고 `track(eventName, data)`로 사용자 정의 이벤트를 전송할 수 있습니다. **주요 기능** - **제로 구성 시작** – 스크립트 태그 추가 또는 npm 가져오기만으로 데이터 수집을 시작할 수 있습니다. - **자동 페이지뷰 감지** – SDK가 탐색 이벤트를 감시하여 추가 코드 없이 `pageview` 페이로드를 전송합니다. - **사용자 정의 이벤트 추적** – 개발자는 이름과 선택적 페이로드와 함께 `track`을 호출하여 모든 상호작용을 기록할 수 있습니다. - **디바이스 포인팅** – 캔버스 기반 포인팅이 프라이버시를 존중하면서 방문자를 고유하게 식별합니다. - **오프라인 큐** – 전송 실패한 이벤트는 로컬 스토리지에 저장되어 나중에 재시도되어 데이터 유실을 최소화합니다. - **세션 관리** – 세션은 자동으로 생성되며 구성 가능한 타임아웃(기본 30분) 후 만료됩니다. - **구성 가능한 배치** – 이벤트를 단일 요청으로 그룹화하여 네트워크 오버헤드를 줄입니다. **설치** - **CDN** – HTML에서 UMD 번들을 직접 포함하고 `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })` 호출. - **npm** – `npm install @weavefox/tracker` 실행 후 함수 가져오기: `import { init, track, setUserId } from '@weavefox/tracker';`. **공개 API** | 메서드 | 목적 | |--------|------| | `init(config)` | 엔드포인트, appId, 선택적 플래그로 SDK 초기화. | | `track(eventName, data)` | 사용자 정의 이벤트 전송. | | `trackPageview(data)` | 페이지 뷰 수동 기록 (기본값 자동 활성화). | | `setUserId(userId)` | 로그인한 사용자를 이후 이벤트와 연결. | | `getFingerprint()` | 생성된 디바이스 포인팅 반환. | | `flush()` | 대기 중인 이벤트를 즉시 전송. | **설정 옵션** ```javascript WFTK.init({ endpoint: 'required', // 수집 서비스 URL appId: 'optional', // 애플리케이션 식별자 autoPageview: true, // 페이지뷰 자동 추적 debug: false, // 콘솔 디버깅 활성화 enableQueue: true, // 네트워크 실패 시 이벤트 오프라인 저장 sessionTimeout: 1800000, // 세션 유휴 타임아웃 (ms, 기본 30분) maxEventsPerSession: 1000 // 세션당 이벤트 상한선 }); ``` **페이로드 형식** – 각 요청은 선택적 `appId`와 `events` 배열을 포함한 JSON 바디를 포함합니다. 각 이벤트에는 필수 `event` 이름, `timestamp`, `nonce`(중복 제거용), `fingerprint`, 시스템 수집 컨텍스트(URL, 제목, 디바이스 정보 등)를 포함하는 `data` 객체가 포함됩니다. 사용자가 정의한 필드는 분석 데이터와 비즈니스 데이터를 분리하기 위해 `biz` 하위 객체에 배치됩니다. **서버 측 고려사항** - **타임스탬프 유효성 검사** – 재생 공격을 방지하기 위해 5분 초과 이벤트 거부. - **Nonce 중복 제거** – 일관성 보장을 위해 24시간 TTL과 함께 Redis 등에 nonce 저장. - **Rate 제한** – 남용 방지를 위해 IP 및 포인팅별 제한 적용. - **애플리케이션 식별** – 명시적 `appId` 선호; 필요시 요청 `Referer` 호스트로 폴백. - **Express 핸들러 예시** – README에는 타임스탬프 검증, nonce 확인, 이벤트 영구 저장을 수행하는 간결한 Node.js 코드 스니펫이 제공됩니다. **라이선스** – MIT 라이선스에 따라 배포되며, 오픈소스 및 상업용 프로젝트 모두에서 제한 없이 사용 가능합니다. 종합적으로 Tracker SDK는 무거운 플랫폼의 오버헤드 없이 신뢰할 수 있는 클라이언트 사이드 분석이 필요한 개발자를 위한 간단하고 프라이버시 존중 솔루션을 제공합니다.