@vrism/viewer-sdk/README.md

React and Vanilla JavaScript SDK for embedding 3D product viewers powered by Verge3D technology

# VRISM Viewer SDK

![npm version](https://img.shields.io/npm/v/@vrism/viewer-sdk?color=blue)
![license](https://img.shields.io/npm/l/@vrism/viewer-sdk)


**VRISM Viewer SDK**는 패션 상품에 최적화된 초실감 3D 뷰어를 웹 애플리케이션에 쉽게 통합할 수 있는 개발 키트입니다. Verge3D 기술을 기반으로 React와 Vanilla JavaScript 환경을 모두 지원합니다.

현재 FILA, NEPA, K2와 같은 국내 대형 패션 브랜드에서 활용하고 있습니다.

[공식문서 바로가기](https://docs-viewer.vrism.com)

## ✨ 주요 특징

- 🎨 **초실감 3D 렌더링**: 고품질 3D 모델과 텍스처로 몰입감 있는 시각적 경험
- ⚛️ **React & Vanilla JS**: 프레임워크에 관계없이 사용 가능
- 📱 **반응형 디자인**: 데스크톱, 모바일, 태블릿 모든 디바이스 지원
- 📦 **TypeScript 지원**: 완전한 타입 정의로 안전한 개발
- 🌐 **다양한 로딩 방식**: ESM, UMD, CDN 지원

## 🚀 빠른 시작

### 설치

```bash
npm install @vrism/viewer-sdk
```

### 토큰 발급

SDK를 사용하기 위해서는 브랜드별 토큰이 필요합니다. 토큰 발급은 [info@vrism.com](mailto:info@vrism.com)으로 문의 부탁드립니다.

### React 사용법

```jsx
import { VrismViewer } from '@vrism/viewer-sdk';

function ProductViewer() {
  return (
    <div style={{ width: '100%', height: '500px' }}>
      <VrismViewer
        token="your-token-here"
        contentId="your-content-id"
        onLoadScene={() => console.log('뷰어 준비 완료!')}
        onError={(error) => console.error('에러:', error)}
      />
    </div>
  );
}
```

### Vanilla JavaScript 사용법

```javascript
import { VrismViewer } from '@vrism/viewer-sdk/vanilla';

const viewer = VrismViewer.init('viewer-container', {
  token: 'your-token-here',
  contentId: 'your-content-id',
  onLoadScene: () => console.log('뷰어 준비 완료!')
});
```

### CDN 사용 (UMD)

```html
<div id="viewer-container" style="width: 100%; height: 500px;"></div>
<script src="https://cdn.jsdelivr.net/npm/@vrism/viewer-sdk@latest/dist/vanilla/umd.js"></script>
<script>
  const viewer = VrismSDK.VrismViewer.init('viewer-container', {
    token: 'your-token-here',
    contentId: 'your-content-id'
  });
</script>
```

## 🎛️ 주요 기능

### UI 커스터마이징
```jsx
<VrismViewer
  token="your-token"
  contentId="your-content-id"
  ui={{
    viewerBackgroundColor: '#f8f9fa',
    gestureGuide: true,
    fullscreenButton: true
  }}
/>
```

### 뷰어 제어
```jsx
// React
const viewerRef = useRef(null);
viewerRef.current?.setStep(2);
viewerRef.current?.setFullscreenOpen(true);

// Vanilla JS
viewer.setStep(2);
viewer.setFullscreenOpen(true);
```

### 이벤트 처리
```jsx
<VrismViewer
  onLoadUpdate={(progress) => console.log(`로딩: ${progress}%`)}
  onStepChange={(options) => console.log(`스텝: ${options.step}`)}
  onError={(error) => console.error('에러:', error)}
/>
```

## 📋 API 참조

### 이벤트 핸들러
- `onLoadUpdate` - 로딩 진행률 업데이트
- `onLoadScene` - 뷰어 사용 준비 완료
- `onStepChange` - 스텝 변경
- `onError` - 에러 발생

### 제어 메서드
- `setStep(step)` - 스텝 이동
- `setGestureGuideShow(show)` - 제스처 가이드 표시 제어
- `setFullscreenOpen(open)` - 전체화면 제어
- `getClickedPosition()` - 3D 위치 선택
- `getConfig()` - 현재 설정 조회

## 📱 지원 환경

- **브라우저**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
- **프레임워크**: React 18+, Vue.js, Angular (Vanilla JS 모드), Next.js
- **디바이스**: 데스크톱, 모바일 (iOS 14+, Android 8+), 태블릿

## 📚 더 자세한 정보

- **[🔗 공식 문서](https://docs-viewer.vrism.com)** - 전체 API 문서 및 고급 사용법
- **[🎯 React 가이드](https://docs-viewer.vrism.com/sdk/basic-usage/react)** - React 환경 상세 사용법
- **[🛠️ Vanilla JS 가이드](https://docs-viewer.vrism.com/sdk/basic-usage/vanilla)** - 순수 JavaScript 사용법
- **[🎨 커스터마이징](https://docs-viewer.vrism.com/sdk/customization)** - UI 테마 및 스타일 커스터마이징
- **[❓ FAQ](https://docs-viewer.vrism.com/sdk/faq)** - 자주 묻는 질문

## 🤝 지원 및 문의

- 📧 **기술 지원 및 버그 제보**: [info@vrism.com](mailto:info@vrism.com)

## 📄 라이센스

MIT License

---

**VRISM Viewer SDK**로 차세대 패션 쇼핑 경험을 만들어보세요! 🌟