visitor-analytics

Visitor Analytics SDK는 웹 애플리케이션을 위한 TypeScript 애널리틱스 라이브러리입니다. React, Vue, Svelte, Solid, Astro와 같은 모든 프론트엔드 프레임워크와 바닐라 JavaScript에서 작동합니다. SDK는 프라이버시를 중시하며, 개인 식별 정보를 절대 수집하지 않고 모든 데이터는 익명화됩니다. 주요 기능은 다음과 같습니다: - 주요 프레임워크별 전용 통합 패키지를 통한 프레임워크 독립 동작. - 커스텀 수집기, 스토리지 어댑터 및 플러그인을 허용하는 모듈형 플러그인 기반 아키텍처. - strict TypeScript 정의 및 any 타입 없는 타입 안전 API. - 필요한 부분만 번들에 포함되는 트리셰이크 가능한 ESM 모듈. - 패시브 리스너, requestIdleCallback, debounce 처리기, 배치된 DOM 읽기를 활용한 제로 런타임 의존성 및 최적화된 성능. - 네트워크가 사용 가능할 때 동기화되는 큐를 통한 오프라인 지원, 지수 백오프 재시도 및 페이지 언로드 시 sendBeacon 폴백. - 배치 크기, 플러시 간격, 재시도 제한, 압축, 중복 제거, 세션 시간 제한, 커스텀 데이터 필드 등 구성 가능한 옵션. SDK는 분석 인스턴스를 반환하는 핵심 createAnalytics 함수를 제공합니다. 인스턴스는 시작, 중지, 플러시, 동기화, 실패한 업로드 재시도, 수집기 추가/제거, 플러그인 설치, 저장된 레코드 조회, 데이터 내보내기, 수동 라우트 변경 추적, 이벤트 구독 및 인스턴스 폐기와 같은 메서드를 갖추고 있습니다. 수집기는 다양한 데이터를 수집합니다: 브라우저 이름 및 버전, 장치 OS 및 플랫폼, 화면 해상도, 성능 지표(네비게이션 타이밍, 페인트 타이밍, LCP, CLS, INP), 환경 정보(타임존, 언어, 색상 체계), 기능 지원(WebGL, WebGPU, WASM, Service Worker) 및 사용자 상호작용(세션 지속 시간, 스크롤 깊이, 클릭 횟수, 라우트 변경, UTM 파라미터) 등입니다. 모든 수집기는 선택사항이며 커스텀 구현으로 확장할 수 있습니다. 스토리지 어댑터로는 인메모리, localStorage, IndexedDB가 제공되며 Redis 어댑터 같은 커스텀 백엔드를 삽입할 수 있습니다. 업로더는 레코드를 배치 처리하고, 지수 백오프로 재시도를 처리하며, 배치를 중복 제거하고, 브라우저가 CompressionStream을 지원하는 경우 페이로드를 압축할 수 있습니다. 통합 예시에는 React(AnalyticsProvider, useAnalytics, usePageView), Vue(createAnalyticsPlugin, useVueAnalytics), Svelte(createAnalyticsStore), SolidJS(AnalyticsProvider, createAnalyticsHook), Astro 및 일반 JavaScript가 포함되어 있습니다. 각 통합은 SDK 초기화, 수집된 데이터 접근, 수동 업로드 트리거 방법을 보여줍니다. SDK에는 플러그인 시스템이 포함되어 있습니다. 플러그인은 설치 시 추가 수집기를 등록하거나 동작을 수정하며, 제거 시 정리할 수 있습니다. AB 테스트 플러그인 예시는 모든 레코드에 현재 실험 변형을 추가합니다. 프라이버시 보장은 명시적입니다: 이름, 이메일, 비밀번호, 쿠키 내용, 양식 입력값, 정확히 일치하는 IP 주소, GPS 좌표, 키스트rokes, 클릭 좌표 또는 영구 지문 식별자는 절대 수집되지 않습니다. 세션 식별자는 각 인스턴스에 대해 생성된 임의 UUID이며 세션 간에 유지되지 않습니다. 알려진 제한사항으로는 활동 기반 세션 시간 제한, 다중 탭 환경에서 localStorage 사용 시 비원자성 쓰기(IndexedDB 권장), gzip 압축은 최근 브라우저 지원이 필요합니다. 성능 최적화는 패시브 이벤트 리스너, 무거운 작업을 위한 requestIdleCallback, debounce된 스크롤 및 리사이즈 처리, 지연 수집기 초기화, requestAnimationFrame을 통한 배치 DOM 읽기, 언로드 시 navigator.sendBeacon을 통한 신뢰성 있는 전송으로 구성됩니다. SDK는 MIT 라이선스로 배포됩니다.