VRISM Viewer SDK
가이드
SDK
릴리즈 노트
가이드
SDK
릴리즈 노트

Vanilla JavaScript API

Vanilla JavaScript 환경에서 VRISM 뷰어를 사용할 수 있습니다. 주로 HTML script 태그를 통해 로드하여 사용합니다.

기본 사용법

HTML 스크립트 태그 사용 (권장)

<!DOCTYPE html>
<html>
<head>
  <title>VRISM Viewer</title>
</head>
<body>
  <div id="viewer-container" style="width: 100%; height: 500px;"></div>
  
  <!-- VRISM SDK 로드 -->
  <script src="https://unpkg.com/@vrism/viewer-sdk@0.1.0/dist/vanilla/umd.js"></script>
  <script>
    // 뷰어 초기화
    const viewer = VrismSDK.VrismViewer.init('viewer-container', {
      token: 'your-token-here',
      contentId: 'your-content-id',
      config: {
        camera: {
          autoRotation: -2,
          controls: {
            enableZoom: true,
            enablePan: true,
            enableRotate: true
          }
        },
        ui: {
          viewerBackgroundColor: '#ffffff',
          gestureGuide: true,
          fullscreenButton: true
        }
      }
    });

    // 이벤트 핸들러 설정
    viewer.onLoadScene = () => {
      console.log('뷰어 사용 준비 완료');
    };

    viewer.onStepChange = (options) => {
      console.log('스텝 변경:', options.step, options.direction);
    };

    viewer.onError = (error) => {
      console.error('뷰어 에러:', error);
    };
  </script>
</body>
</html>

ES6 모듈 사용 (선택사항)

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

const viewer = VrismViewer.init('viewer-container', {
  token: 'your-token-here',
  contentId: 'your-content-id',
  config: {
    camera: {
      autoRotation: -2,
      controls: {
        enableZoom: true,
        enablePan: true,
        enableRotate: true
      }
    },
    ui: {
      viewerBackgroundColor: '#ffffff',
      gestureGuide: true,
      fullscreenButton: true
    }
  }
});

// 이벤트 핸들러 설정
viewer.onLoadScene = () => {
  console.log('뷰어 사용 준비 완료');
};

viewer.onStepChange = (options) => {
  console.log('스텝 변경:', options.step, options.direction);
};

viewer.onError = (error) => {
  console.error('뷰어 에러:', error);
};

메서드

getConfig(): object

현재 뷰어 설정을 반환합니다.

const config = viewer.getConfig();
console.log('현재 설정:', config);

setGestureGuideShow(show?: boolean): void

제스처 가이드 표시를 제어합니다.

viewer.setGestureGuideShow(false); // 숨기기
viewer.setGestureGuideShow(true);  // 표시

setFullscreenOpen(open?: boolean): void

전체화면 모드를 제어합니다.

viewer.setFullscreenOpen(true);  // 전체화면 열기
viewer.setFullscreenOpen(false); // 전체화면 닫기

setStep(step: number): void

스텝을 설정합니다.

viewer.setStep(2); // 2번째 스텝으로 이동

onVTOClick(): void

VTO 기능을 트리거합니다.

viewer.onVTOClick();

getClickedPosition(): Promise<PickedPositionData | null>

사용자가 3D 모델에서 클릭한 위치를 반환합니다.

⚠️ 중요: 이 메서드는 step 기능이 활성화되고 step 항목이 1개 이상 설정된 상태에서만 정상적으로 동작합니다. config.ui.step.enabled: true와 config.ui.step.items 배열을 설정하세요.

// step 기능 활성화 및 항목 설정 필요
const viewer = VrismSDK.VrismViewer.init('viewer-container', {
  token: 'your-token-here',
  contentId: 'your-content-id',
  config: {
    ui: {
      step: {
        enabled: true,  // 필수 설정
        items: [        // 1개 이상 필수
          {
            id: 1,
            name: '전체 보기',
            order: 1,
            anchor: {
              desktop: {
                position: { x: 0, y: 0, z: 5 },
                target: { x: 0, y: 0, z: 0 }
              }
            }
          }
        ]
      }
    }
  }
});

const position = await viewer.getClickedPosition();
if (position) {
  console.log('선택된 위치:', position.anchor.position);
}

reload(config?: ViewerConfig): Promise

뷰어를 새로운 설정으로 리로드합니다.

await viewer.reload({
  ui: { viewerBackgroundColor: '#000000' }
});

destroy(): void

뷰어 리소스를 정리합니다.

viewer.destroy();

이벤트 핸들러

onLoadScene

뷰어가 완전히 준비되어 사용 가능할 때 호출됩니다.

viewer.onLoadScene = () => {
  console.log('뷰어 사용 준비 완료');
  // 이 시점에서 API 메서드 호출 가능
};

onLoadFinish

로딩 진행률이 100%에 도달했을 때 호출됩니다.

viewer.onLoadFinish = () => {
  console.log('로딩 완료');
};

onLoadUpdate

로딩 진행률 업데이트 시 호출됩니다.

viewer.onLoadUpdate = (percentage) => {
  console.log(`로딩 진행률: ${percentage}%`);
};

onStepChange

스텝이 변경되었을 때 호출됩니다.

viewer.onStepChange = (options) => {
  console.log('스텝 변경:', options.step, options.direction);
};

onChange

뷰어 상태가 변경되었을 때 호출됩니다.

viewer.onChange = () => {
  console.log('뷰어 상태 변경');
};

onError

에러 발생 시 호출됩니다.

viewer.onError = (error) => {
  console.error('뷰어 에러:', error);
};

onFullscreenChange

전체화면 모드 변경 시 호출됩니다.

viewer.onFullscreenChange = (isFullscreen) => {
  console.log('전체화면 모드:', isFullscreen);
};

Vanilla JavaScript 전용 타입 정의

ViewerInitOptions

interface ViewerInitOptions {
  token: string
  contentId: string
  config?: ViewerConfig
}

공통 타입들

공통으로 사용되는 ViewerConfig, CameraConfig, UIConfig, Position, PickedPositionData, StepItem 등의 타입은 공통 타입 정의를 참조하세요.

참고: React 버전과 동일한 기능을 제공하지만, React 환경이 아닌 곳에서 사용할 때 Vanilla JavaScript API를 사용하세요.

ON THIS PAGE