@datatica/snippet

Datatica는 현대적인 웹 애플리케이션을 위한 경량 웹 분석 라이브러리입니다. ClickHouse 데이터베이스와 통합되어 실시간 이벤트 추적, 개인정보 보호, 성능 최적화 기능을 제공합니다.

🚀 주요 기능

핵심 기능

• ✅ 실시간 이벤트 추적: 클릭, 페이지 뷰, 폼 제출, 스크롤 등
• ✅ ClickHouse 통합: 고성능 데이터베이스 연동
• ✅ 자동 추적: 설정 없이 바로 사용 가능
• ✅ 세션 관리: 사용자 및 세션 자동 식별
• ✅ 배치 처리: 효율적인 데이터 전송

개인정보 보호

• 🔒 GDPR 준수: 완전한 개인정보 보호 지원
• 🔒 Do Not Track: 브라우저 설정 자동 인식
• 🔒 민감 정보 필터링: 자동 데이터 마스킹
• 🔒 동의 관리: 세밀한 추적 동의 제어

성능 최적화

• ⚡ 이벤트 Throttling: 고빈도 이벤트 제한
• ⚡ 메모리 관리: 자동 메모리 정리
• ⚡ 배치 최적화: 중복 제거 및 압축
• ⚡ 오프라인 지원: 연결 복구 시 자동 전송

에러 처리

• 🛡️ 재시도 로직: 네트워크 오류 자동 복구
• 🛡️ 오프라인 모드: 연결 끊김 상황 대응
• 🛡️ 에러 통계: 상세한 에러 분석

📦 설치

NPM으로 설치

npm install @datatica/snippet

Yarn으로 설치

yarn add @datatica/snippet

CDN 사용

<script src="https://unpkg.com/@datatica/snippet/dist/datatica.umd.js"></script>

🔧 빠른 시작

1. 기본 설정

import { Datatica } from "@datatica/snippet";

const datatica = new Datatica({
  endpoint: "https://your-clickhouse-server.com",
  projectId: "your-project-id",
  autoTrack: true,
  debug: false,
});

// 초기화
await datatica.initialize();

2. 이벤트 추적

// 커스텀 이벤트 추적
datatica.track("button_click", {
  button_id: "signup-btn",
  page: "landing",
  user_type: "visitor",
});

// 구매 이벤트 추적
datatica.track("purchase", {
  product_id: "prod_123",
  price: 29.99,
  currency: "USD",
  quantity: 1,
});

3. 자동 추적 활성화

// 자동 추적 활성화 (기본값)
datatica.enableAutoTracking();

// 자동 추적 비활성화
datatica.disableAutoTracking();

📖 상세 가이드

설정 옵션

const config = {
  // 필수 설정
  endpoint: "https://your-clickhouse-server.com",
  projectId: "your-project-id",

  // 자동 추적 설정
  autoTrack: true,

  // 배치 설정
  batchSize: 10,
  flushInterval: 5000,

  // 개인정보 보호
  respectDoNotTrack: true,
  maskTextContent: true,
  allowedDomains: ["example.com"],

  // 성능 최적화
  performanceOptimization: true,
  maxEventsPerSecond: 100,
  maxEventsPerMinute: 1000,
  maxMemoryUsageMB: 50,

  // 에러 처리
  maxRetries: 3,
  retryDelay: 1000,

  // 디버깅
  debug: false,
};

개인정보 보호 설정

// GDPR 동의 설정
datatica.setGDPRConsent({
  analytics: true,
  marketing: false,
  functional: true,
});

// 추적 허용 여부 확인
if (datatica.canTrack()) {
  datatica.track("user_action", { action: "click" });
}

// 개인정보 보호 설정 초기화
datatica.resetPrivacySettings();

성능 모니터링

// 성능 통계 조회
const stats = datatica.getPerformanceStats();
console.log("Performance Stats:", stats);

// 메모리 정리 강제 실행
datatica.forceMemoryCleanup();

// 현재 큐 크기 확인
const queueSize = datatica.getQueueSize();
console.log("Queue Size:", queueSize);

연결 상태 확인

// 연결 상태 및 통계 조회
const status = await datatica.getConnectionStatus();
console.log("Connection Status:", status);

// 오프라인 이벤트 수동 처리
const processedCount = await datatica.processOfflineEvents();
console.log(`Processed ${processedCount} offline events`);

🌐 브라우저 지원

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11 (부분 지원)

📊 ClickHouse 테이블 스키마

CREATE TABLE events (
  event_id String,
  project_id String,
  user_id String,
  session_id String,
  event_type String,
  event_name String,
  timestamp DateTime64(3),
  page_url String,
  page_title String,
  referrer_url String,
  user_agent String,
  screen_width UInt16,
  screen_height UInt16,
  lib_version String,
  utm_source Nullable(String),
  utm_medium Nullable(String),
  utm_campaign Nullable(String),
  attributes Map(String, String)
) ENGINE = MergeTree()
ORDER BY (project_id, event_type, timestamp);

🔧 고급 사용법

커스텀 이벤트 컬렉터

// 커스텀 속성과 함께 이벤트 수집
datatica.track("video_play", {
  video_id: "video_123",
  video_title: "Tutorial Video",
  duration: 300,
  quality: "1080p",
  autoplay: false,
});

배치 이벤트 처리

// 대량 이벤트 배치 처리
const events = [
  { event_type: "page_view", page_url: "/home" },
  { event_type: "click", element_id: "btn_1" },
  { event_type: "scroll", scroll_depth: 50 },
];

await datatica.processBulkEvents(events);

에러 처리 및 모니터링

// 에러 통계 조회
const errorStats = datatica.getErrorStats();
console.log("Error Stats:", errorStats);

// 에러 목록 조회
const errors = datatica.getErrors();
console.log("Errors:", errors);

// 에러 목록 비우기
datatica.clearErrors();

🧪 테스트

# 전체 테스트 실행
npm test

# 감시 모드로 테스트
npm run test:watch

# 커버리지 리포트 생성
npm run test:coverage

🚀 배포

# 프로덕션 빌드
npm run build

# NPM 배포
npm run publish:npm

# 베타 버전 배포
npm run publish:beta

📝 변경사항

자세한 변경사항은 CHANGELOG.md를 참조하세요.

🤝 기여하기

기여를 원하시는 분은 CONTRIBUTING.md를 참조하세요.

📄 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

🆘 지원

• 📧 이메일: [email protected]
• 💬 디스코드: Datatica Community
• 🐛 이슈: GitHub Issues
• 📖 문서: docs.datatica.com

🏆 크레딧

Datatica는 다음 오픈소스 프로젝트들을 기반으로 구축되었습니다:

• ClickHouse - 고성능 데이터베이스
• Vite - 빠른 빌드 도구
• TypeScript - 타입 안전성
• Jest - 테스트 프레임워크