소개

시작하기

뷰어 배포부터 첫 저장까지, JS가 동작하는 환경이면 5분 안에 끝나는 통합 절차입니다.

사전 준비

Inko 라이센스 패키지 — 계약 후 전달되는 빌드 산출물(dist)입니다. 뷰어 본체와 SDK 래퍼가 포함되어 있습니다.
정적 파일을 서빙할 수 있는 웹 서버 — Nginx·Apache·Tomcat·IIS 등 무엇이든 가능합니다.

별도 설치가 없습니다

npm 패키지 설치·번들러 설정·서버 모듈 설치가 모두 필요 없습니다. 정적 파일을 올리고 <script> 한 줄을 추가하는 것이 통합의 전부입니다.

1단계 — 뷰어 배포

라이센스 패키지의 산출물을 고객사 서버 /pdfv/ 경로에 그대로 업로드합니다.

배포 후 디렉터리 구조

customer-server/
└─ pdfv/                  ← 라이센스 패키지의 dist 산출물 전체
   ├─ index.html          ← 뷰어 본체 (iframe으로 로드됨)
   ├─ assets/             ← 뷰어 JS·CSS 번들
   └─ sdk/
      └─ pdfv-sdk.js      ← 호스트 페이지에서 로드하는 SDK 래퍼

Same-Origin Sub-Path 권장

뷰어를 호스트 페이지와 같은 도메인의 하위 경로(예: https://erp.example.com/pdfv/)에 두면 CORS 설정이 전혀 필요 없고, 폐쇄망·내부망 환경에서도 추가 구성 없이 동작합니다. 별도 도메인에 두는 경우는 FAQ의 크로스 도메인 항목을 참고하세요.

2단계 — SDK 로드

PDF를 띄울 페이지에서 SDK 스크립트를 로드합니다. 전역 객체 Inko (별칭 PdfViewer)가 등록됩니다.

호스트 페이지 html

<!-- 호스트 페이지 (고객사 웹 시스템의 아무 페이지) -->
<script src="/pdfv/sdk/pdfv-sdk.js"></script>

3단계 — 마운트

컨테이너 요소를 두고 Inko.mount()를 호출하면, 컨테이너 안에 뷰어 iframe이 생성되고 PDF가 로드됩니다.

최소 마운트 html

<div id="pdf-container" style="width:100%; height:80vh"></div>

<script>
  var viewer = Inko.mount('#pdf-container', {
    src: '/pdfv/index.html',          // 뷰어 본체 URL (필수)
    pdfUrl: '/files/document.pdf',    // 표시할 PDF
    fileName: 'document.pdf'
  });
</script>

src는 1단계에서 배포한 뷰어 본체의 URL입니다. 컨테이너의 크기가 곧 뷰어의 크기이므로, 컨테이너에 명시적인 높이를 지정해야 합니다.

전체 예제 — 저장까지

실제 운영에서는 저장 콜백(onSave)으로 받은 canvasData를 자체 DB에 적재합니다. 아래는 저장·이어서 편집·에러 처리까지 포함한 전체 흐름입니다.

contract-view.html — 전체 예제 html

<div id="pdf-container" style="width:100%; height:80vh"></div>
<script src="/pdfv/sdk/pdfv-sdk.js"></script>
<script>
  var viewer = Inko.mount('#pdf-container', {
    src: '/pdfv/index.html',
    pdfUrl: '/files/contract.pdf',
    fileName: 'contract.pdf',

    // 직전에 저장해 둔 버전이 있으면 그 지점부터 이어서 편집.
    // SAVED_CANVAS_DATA는 예시용 이름 — 고객사 서버가 페이지에 심어 주는 값입니다 (없으면 undefined)
    initialCanvasData: window.SAVED_CANVAS_DATA || undefined,

    onReady: function () {
      console.log('뷰어 준비 완료');
    },
    onSave: function (canvasData, ok, msg) {
      if (!ok) { alert('저장 실패: ' + msg); return; }
      // canvasData를 자체 DB에 INSERT — append-only 버전 한 건
      fetch('/api/annotations', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ docId: 123, canvasData: canvasData })
      });
    },
    onError: function (err) {
      console.error('[Inko]', err);
    }
  });

  // 외부 버튼에서 저장 트리거도 가능
  // document.querySelector('#save-btn').onclick = function () { viewer.save(); };
</script>

예제 속 이름은 자리표시자입니다

window.SAVED_CANVAS_DATA·/api/annotations·docId: 123처럼 예제에 등장하는 변수·API 경로·ID는 설명용 이름입니다. 고객사 시스템의 실제 변수와 엔드포인트로 바꿔 사용하세요. 이 규칙은 모든 문서의 예제에 동일하게 적용됩니다.

동작 확인 체크리스트

확인 항목	기대 동작
페이지 접속	컨테이너 영역에 뷰어 툴바와 PDF 첫 페이지가 표시됩니다.
펜으로 드로잉	PDF 위에 필기가 그려지고 `onChange` 콜백이 호출됩니다.
저장 버튼 클릭	`onSave` 콜백에 `canvasData` 문자열이 전달됩니다.
저장 후 재접속 + `initialCanvasData` 주입	직전 작업이 복원된 상태로 열립니다.

여기까지 확인되면 통합이 완료된 것입니다. 다음 단계로 저장과 버전 관리에서 버전 테이블 설계를, 커스터마이징에서 브랜드 적용 방법을 확인하세요. 진행 중 막히는 부분이 있으면 FAQ · 트러블슈팅에서 증상별 해결 방법을 찾아보세요.