@vircle/sdk-react-native

React Native 애플리케이션을 위한 고성능 데이터 수집 SDK입니다. TypeScript로 작성되었으며 iOS, Android 플랫폼을 모두 지원합니다.

🚀 주요 기능

• 📱 네이티브 통합: React Native 앱에 최적화된 이벤트 추적
• 🔐 페이로드 암호화: AES-256-GCM + RSA-OAEP 하이브리드 암호화
• 📊 자동 컨텍스트 수집: 디바이스, 앱, 네트워크 정보 자동 수집
• 💾 오프라인 지원: 네트워크 연결이 없을 때 이벤트 로컬 저장
• ⚡ 성능 최적화: 배치 처리 및 효율적인 메모리 사용

📦 설치

# npm
npm install @vircle/sdk-react-native @react-native-async-storage/async-storage @react-native-community/netinfo

# yarn
yarn add @vircle/sdk-react-native @react-native-async-storage/async-storage @react-native-community/netinfo

# pnpm
pnpm add @vircle/sdk-react-native @react-native-async-storage/async-storage @react-native-community/netinfo

iOS 설정

cd ios && pod install

암호화 지원 (선택사항)

페이로드 암호화 기능을 사용하려면 암호화 라이브러리를 추가로 설치해야 합니다:

# 권장: react-native-quick-crypto
npm install react-native-quick-crypto
cd ios && pod install

# index.js 최상단에 추가
import 'react-native-quick-crypto';

자세한 암호화 설정 방법은 암호화 가이드를 참조하세요.

📊 배치 처리

SDK는 효율적인 네트워크 사용을 위해 이벤트를 배치로 처리합니다. 자세한 내용은 배치 처리 가이드를 참조하세요.

🎯 빠른 시작

기본 사용법

import { VircleReactNative } from '@vircle/sdk-react-native';

// SDK 초기화
const vircle = new VircleReactNative({
  apiKey: 'your-api-key',
  debug: __DEV__, // 개발 환경에서만 디버그 모드
});

// SDK 초기화
await vircle.initialize();

// 이벤트 추적
vircle.track('button_clicked', {
  button_id: 'purchase',
  product_id: 'premium_plan',
  price: 99.99
});

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

🔧 고급 설정

전체 설정 옵션

const vircle = new VircleReactNative(
  {
    // 필수 설정
    apiKey: 'your-api-key',
    
    // 선택 설정
    debug: true, // 디버그 로그 출력
    
    // 배치 처리 설정
    batch: {
      size: 30,              // 배치 크기 (기본값: 50)
      flushInterval: 15000,  // 배치 전송 간격 (기본값: 10000ms = 10초)
      timeout: 5000,         // 배치 타임아웃 (기본값: 5000ms)
      maxBytes: 1048576,     // 최대 배치 크기 (기본값: 1MB)
      compression: true      // 압축 여부 (기본값: true)
    },
    
    // 재시도 설정
    retry: {
      maxAttempts: 3,        // 최대 재시도 횟수 (기본값: 3)
      initialDelay: 1000,    // 초기 재시도 대기시간 (기본값: 500ms)
      maxDelay: 30000,       // 최대 재시도 대기시간 (기본값: 30000ms)
      exponentialBackoff: true // 지수 백오프 사용 (기본값: true)
    },
    
    // 큐 설정
    queue: {
      maxSize: 1000,         // 최대 큐 크기 (기본값: 1000)
      strategy: 'fifo'       // 큐 처리 전략 (기본값: 'fifo')
    }
  },
  {
    // 고급 옵션
    enableEncryption: true,  // 페이로드 암호화
    flushOnBackground: true, // 백그라운드 전환 시 이벤트 플러시 (기본값: true)
    contextCacheTime: 60000  // 컨텍스트 캐시 시간 (기본값: 60000ms = 1분)
  }
);

커스텀 컨텍스트

모든 이벤트에 포함될 커스텀 컨텍스트 설정:

// 글로벌 컨텍스트 설정
vircle.setContext({
  experiment: 'feature_flag_v2',
  ab_group: 'control',
  app_version: '1.2.3'
});

// 특정 이벤트에만 컨텍스트 추가
vircle.track('purchase', 
  { product_id: 'abc-123' },
  { 
    context: {
      campaign: 'summer_sale',
      referrer: 'instagram'
    }
  }
);

🔐 보안

API 키 보안

• 클라이언트용 API 키는 데이터 수집 권한만 제공
• 환경별로 다른 API 키 제공 (development, production)

페이로드 암호화

• 민감한 데이터 보호를 위한 엔드투엔드 페이로드 암호화 (AES-256-GCM + RSA-OAEP)
• 추가 암호화 라이브러리 설치 필수: react-native-quick-crypto

const vircle = new VircleReactNative(
  { apiKey: 'your-api-key' },
  {
	  enableEncryption: true // 암호화 활성화
  }
);

🐛 문제 해결

일반적인 문제

1. "암호화 라이브러리가 설치되지 않았습니다" 오류

   • react-native-quick-crypto 설치 확인
   • iOS: pod install 실행
   • Metro 캐시 정리: npx react-native start --reset-cache

2. 암호화 실패 오류 (Encryption failed)

   • 현재 React Native 환경에서 암호화 호환성 문제가 있을 수 있습니다
   • 임시 해결: 암호화 비활성화

     const vircle = new VircleReactNative({
       apiKey: 'your-api-key',
       // encryption 설정 제거 또는 enabled: false
     });

3. 이벤트가 전송되지 않음

   • API 키 확인
   • 네트워크 연결 확인
   • debug: true로 로그 확인

4. 빌드 실패

   • 네이티브 의존성 재설치
   • iOS: cd ios && pod deintegrate && pod install
   • Android: cd android && ./gradlew clean

디버깅

// 디버그 모드 활성화
const vircle = new VircleReactNative({
  apiKey: 'your-api-key',
  debug: true // 상세 로그 출력
});

// SDK 상태 확인
console.log('SDK Status:', vircle.getStatus());
console.log('Online:', await vircle.isOnline());

// 이벤트 강제 전송
await vircle.flush();

📚 API 레퍼런스

VircleReactNative

| 메서드 | 설명 | 반환값 | |--------|------|--------| | initialize() | SDK 초기화 | Promise<void> | | track(event, properties?, context?) | 이벤트 추적 | Promise<void> | | identify(userId, traits?, context?) | 사용자 식별 | Promise<void> | | setContext(context) | 글로벌 컨텍스트 설정 | void | | setGlobalProperties(props) | 모든 이벤트에 자동 병합되는 전역 속성 설정 | void | | clearGlobalProperties() | 전역 속성 초기화 | void | | getAnonymousId() | 크로스 도메인 어트리뷰션용 anonymousId 조회 | string \| undefined | | flush() | 큐에 있는 이벤트 전송 | Promise<void> | | reset() | 사용자 정보 초기화 | Promise<void> | | cleanup() | SDK 정리 | Promise<void> | | isOnline() | 네트워크 연결 상태 확인 | Promise<boolean> | | getScreenDimensions() | 화면 크기 정보 | { width: number, height: number } |