CRM Analytics SDK

@zunstar/crm-analytics - 웹 애플리케이션을 위한 강력한 사용자 행동 추적 SDK

웹사이트에서 사용자 이벤트를 수집하여 CRM API로 전송하는 TypeScript 기반 SDK입니다. Mixpanel, Amplitude와 같은 업계 표준 패턴을 따르며, 강력한 기능과 뛰어난 개발자 경험을 제공합니다.

✨ 주요 특징

• ✅ init() 방식 초기화 - 업계 표준 패턴 (Mixpanel, Amplitude 스타일)
• ✅ 이벤트 큐 시스템 - 초기화 전에 호출된 이벤트들을 자동으로 큐에 저장 후 처리
• ✅ 자동 데이터 수집 - 브라우저, 디바이스, 성능 정보 자동 수집
• ✅ 플러그인 시스템 - ErrorTracker, PerformanceTracker 등 확장 가능
• ✅ 보안 강화 - XSS 방지, 레이트 리미팅, 데이터 새니타이징
• ✅ TypeScript 완전 지원 - 100% 타입 안전성 보장

📦 설치

NPM 패키지 설치 (배포 후)

pnpm install @zunstar/crm-analytics
# 또는
npm install @zunstar/crm-analytics
# 또는
yarn add @zunstar/crm-analytics

로컬 개발용

# SDK 빌드
cd crm_analytics_sdk
pnpm install
pnpm build

# 프로젝트에서 설치
cd your-project
pnpm install ../crm_analytics_sdk

🚀 빠른 시작

1. SDK 초기화

// src/lib/analytics.ts
import { CRMAnalytics } from '@zunstar/crm-analytics';

const analytics = new CRMAnalytics();
export default analytics;

2. 앱 시작 시 초기화

// src/main.tsx
import analytics from './lib/analytics';

const initializeApp = async () => {
  try {
    await analytics.init(import.meta.env.VITE_CRM_CLIENT_KEY!, {
      serverUrl: 'https://crm-api.petvers.co.kr',
      debug: true
    });

    console.log('✅ CRM Analytics 초기화 완료');
  } catch (error) {
    console.error('❌ Analytics 초기화 실패:', error);
  }
};

initializeApp();

3. 이벤트 추적

// 페이지뷰 추적
await analytics.page('홈페이지');

// 이벤트 추적
await analytics.track('button_clicked', {
  button_name: 'signup',
  location: 'header'
});

// 사용자 식별
await analytics.identify('user-123', {
  name: 'John Doe',
  email: '[email protected]',
  plan: 'premium'
});

// 클릭 추적
await analytics.click('#signup-button', {
  campaign: 'winter_sale'
});

📚 문서

📖 완전한 사용 가이드

모든 기능, 고급 사용법, 실전 예제, 트러블슈팅이 포함된 상세 문서입니다:

• 기본 사용법: 초기화, 이벤트 추적, 사용자 식별
• 고급 기능: 이벤트 큐, 배치 전송, 세션 관리
• 플러그인 시스템: ErrorTracker, PerformanceTracker, PagePerformanceTracker
• 실전 예제: React 통합, E-commerce 추적, 온보딩 추적
• 아키텍처: 클래스 구조, 데이터 흐름, 자동 수집 데이터
• 트러블슈팅: 일반적인 문제 해결 방법
• API 레퍼런스: 모든 메서드와 옵션 상세 설명

🛠️ 개발 가이드

SDK 개발, 빌드, 기여를 위한 내부 가이드입니다.

🔌 플러그인

ErrorTracker - 에러 자동 추적

import { ErrorTracker } from '@zunstar/crm-analytics';

ErrorTracker.install(analytics, {
  captureUnhandledRejections: true,
  maxStackLength: 1000
});

PerformanceTracker - Web Vitals 측정

import { PerformanceTracker } from '@zunstar/crm-analytics';

PerformanceTracker.install(analytics, {
  measureWebVitals: true  // LCP, FID, CLS 자동 측정
});

PagePerformanceTracker - 페이지 성능 추적

import { PagePerformanceTracker } from '@zunstar/crm-analytics';

PagePerformanceTracker.install(analytics, {
  trackLoadTime: true,
  trackScrollDepth: true,
  scrollThreshold: [25, 50, 75, 100]
});

⚙️ 설정 옵션

await analytics.init('your-client-key', {
  serverUrl: 'https://crm-api.petvers.co.kr',

  // 자동 추적
  autoPageView: false,
  autoClickTrack: false,
  autoErrorTrack: false,

  // 성능 최적화
  enableBatching: false,

  // 세션 설정
  sessionTimeout: 30 * 60 * 1000, // 30분

  // 디버그
  debug: true,

  // 기본 속성
  defaultProperties: {
    app_version: '2.0.0',
    environment: 'production'
  }
});

🎯 React에서 사용

커스텀 훅

// src/hooks/useAnalytics.ts
import { useCallback } from 'react';
import analytics from '@/lib/analytics';

export const useAnalytics = () => {
  const trackEvent = useCallback(async (
    eventName: string,
    properties?: Record<string, any>
  ) => {
    await analytics.track(eventName, properties);
  }, []);

  const trackPageView = useCallback(async (
    pageName: string,
    properties?: Record<string, any>
  ) => {
    await analytics.page(pageName, properties);
  }, []);

  return { trackEvent, trackPageView };
};

컴포넌트에서 사용

import { useAnalytics } from '@/hooks/useAnalytics';

const SignupButton = () => {
  const { trackEvent } = useAnalytics();

  const handleClick = async () => {
    await trackEvent('signup_started', {
      source: 'header_button'
    });
  };

  return <button onClick={handleClick}>회원가입</button>;
};

🔐 자동 수집 데이터

SDK는 다음 정보를 자동으로 수집합니다:

📄 페이지 정보

• URL, 제목, 경로, 리퍼러
• UTM 파라미터 (utm_source, utm_campaign 등)

💻 디바이스/브라우저

• 화면 해상도, 뷰포트 크기
• 브라우저 종류, 버전, OS
• 네트워크 연결 정보 (4G, WiFi 등)
• 하드웨어 정보 (CPU 코어 수, 메모리 등)

⚡ 성능 메트릭

• 페이지 로드 시간
• DOM 준비 시간
• First Paint, First Contentful Paint
• 세션 지속 시간

🔒 보안/프라이버시

• 민감한 폼 데이터 자동 마스킹
• XSS 방지를 위한 데이터 새니타이징
• Do Not Track 설정 준수

🌐 브라우저 지원

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• 모바일 브라우저 (iOS Safari, Chrome Mobile)

📊 서버 요구사항

CRM Analytics SDK는 다음 API 구조와 연동됩니다:

• 인증: x-client-key 헤더로 API 키 전송
• 엔드포인트:
  • POST /auth/verify - API 키 검증
  • POST /events - 단일 이벤트 전송
  • POST /events/batch - 배치 이벤트 전송
• 응답: 202 상태 코드 (이벤트가 큐에 추가됨)

🔧 개발 명령어

# 의존성 설치
pnpm install

# 빌드 (production)
pnpm build

# 개발 모드 (watch 모드)
pnpm dev

# 타입 체크
pnpm type-check

📝 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.

📞 지원 및 문의

• Email: [email protected]
• GitHub: https://github.com/zunstar/

Made with ❤️ by Zunstar