Vircle SDK for React Native applications
npm install @vircle/sdk-react-native
React Native 애플리케이션을 위한 고성능 데이터 수집 SDK입니다. TypeScript로 작성되었으며 iOS, Android 플랫폼을 모두 지원합니다.
- 📱 네이티브 통합: React Native 앱에 최적화된 이벤트 추적
- 🔐 페이로드 암호화: AES-256-GCM + RSA-OAEP 하이브리드 암호화
- 📊 자동 컨텍스트 수집: 디바이스, 앱, 네트워크 정보 자동 수집
- 💾 오프라인 지원: 네트워크 연결이 없을 때 이벤트 로컬 저장
- ⚡ 성능 최적화: 배치 처리 및 효율적인 메모리 사용
``bashnpm
npm install @vircle/sdk-react-native @react-native-async-storage/async-storage @react-native-community/netinfo
$3
bash
cd ios && pod install
`$3
페이로드 암호화 기능을 사용하려면 암호화 라이브러리를 추가로 설치해야 합니다:
bash
권장: react-native-quick-crypto
npm install react-native-quick-crypto
cd ios && pod installindex.js 최상단에 추가
import 'react-native-quick-crypto';
`자세한 암호화 설정 방법은 암호화 가이드를 참조하세요.
📊 배치 처리
SDK는 효율적인 네트워크 사용을 위해 이벤트를 배치로 처리합니다. 자세한 내용은 배치 처리 가이드를 참조하세요.
🎯 빠른 시작
$3
typescript
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: 'user@example.com',
name: 'John Doe',
plan: 'premium'
});
`
🔧 고급 설정
$3
typescript
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분)
}
);
`
$3
모든 이벤트에 포함될 커스텀 컨텍스트 설정:
typescript
// 글로벌 컨텍스트 설정
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'
}
}
);
`🔐 보안
$3
- 클라이언트용 API 키는 데이터 수집 권한만 제공
- 환경별로 다른 API 키 제공 (
, production)$3
- 민감한 데이터 보호를 위한 엔드투엔드 페이로드 암호화 (AES-256-GCM + RSA-OAEP)
- 추가 암호화 라이브러리 설치 필수: react-native-quick-crypto
`typescript
const vircle = new VircleReactNative(
{ apiKey: 'your-api-key' },
{
enableEncryption: true // 암호화 활성화
}
);
`🐛 문제 해결
$3
1. "암호화 라이브러리가 설치되지 않았습니다" 오류
- react-native-quick-crypto 설치 확인
- iOS:
실행
- Metro 캐시 정리: npx react-native start --reset-cache2. 암호화 실패 오류 (Encryption failed)
- 현재 React Native 환경에서 암호화 호환성 문제가 있을 수 있습니다
- 임시 해결: 암호화 비활성화
typescript
const vircle = new VircleReactNative({
apiKey: 'your-api-key',
// encryption 설정 제거 또는 enabled: false
});
`3. 이벤트가 전송되지 않음
- API 키 확인
- 네트워크 연결 확인
-
로 로그 확인4. 빌드 실패
- 네이티브 의존성 재설치
- iOS:
cd ios && pod deintegrate && pod install
- Android: $3
typescript
// 디버그 모드 활성화
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 레퍼런스
$3
| 메서드 | 설명 | 반환값 |
|--------|------|--------|
|
| SDK 초기화 | Promise |
| track(event, properties?, context?) | 이벤트 추적 | Promise |
| identify(userId, traits?, context?) | 사용자 식별 | Promise |
| setContext(context) | 글로벌 컨텍스트 설정 | void |
| flush() | 큐에 있는 이벤트 전송 | Promise |
| reset() | 사용자 정보 초기화 | Promise |
| cleanup() | SDK 정리 | Promise |
| isOnline() | 네트워크 연결 상태 확인 | Promise |
| getScreenDimensions() | 화면 크기 정보 | { width: number, height: number }` |