레퍼런스
API 레퍼런스
현재 통합에 사용하는 주요 공개 API를 설명합니다. 사용 흐름 중심의 설명은 시작하기와 핵심 가이드 문서를 참고하세요.
전역 객체
전역 API js
// NextH self-hosted 데모: <script src="/pdfv/sdk/pdfv-sdk.js">
// npm 패키지: 배포한 sdk/inko-sdk.js 로드 후
window.Inko // 등록되는 브라우저 전역 이름
Inko.mount(target, options) // 뷰어 마운트 → 인스턴스 반환
Inko.version // 현재 로드한 SDK의 버전 문자열
Inko.MESSAGE_TYPES // postMessage 타입 상수 (디버깅·고급 사용)Inko.mount(target, options)
컨테이너에 뷰어 iframe을 생성하고 인스턴스를 반환합니다. target이 가리키는 요소가 없으면 예외를 던집니다.
시그니처 js
const viewer = Inko.mount(target, options)
// target: string(CSS 선택자) 또는 Element
// options: 아래 표 참고 — src만 필수
// 반환: viewer 인스턴스 (아래 '인스턴스 메서드' 참고)옵션 — 기본
| 옵션 | 타입 | 설명 | |
|---|---|---|---|
src | string | 필수 | 뷰어 본체 URL (예: /pdfv/index.html). 이 URL의 origin이 postMessage 검증 기준이 됩니다. |
pdfUrl | string | 선택 | 초기 로드할 PDF URL. pdfBase64와 함께 지정 시 pdfBase64 우선. |
pdfBase64 | string | 선택 | 초기 로드할 PDF의 Base64 문자열 (data: 접두어 제외). |
fileName | string | 선택 | 뷰어에 표시할 파일명. 기본 'document.pdf'. |
readOnly | boolean | 선택 | true면 편집 도구·저장 비활성. 기본 false. |
initialCanvasData | string | 선택 | 직전 저장본(canvasData) — 그 시점부터 이어서 편집. 호스트 앱은 내부 형식을 해석하지 않고 저장한 값을 그대로 재주입할 수 있습니다. |
width | string | 선택 | iframe 너비 CSS 값. 기본 '100%'. |
height | string | 선택 | iframe 높이 CSS 값. 기본 '100%'. |
title | string | 선택 | iframe title 속성 (접근성). 기본 'PDF Viewer'. |
iframeAttributes | object | 선택 | iframe에 추가할 임의 속성 — 예: { sandbox: '...', loading: 'lazy' }. |
옵션 — 이벤트 콜백
| 콜백 | 시그니처 | 호출 시점 |
|---|---|---|
onReady | () => void | 뷰어 초기화 완료. 이 시점부터 큐잉 없이 즉시 명령이 전달됩니다. |
onPdfLoaded | () => void | PDF 로드와 첫 페이지 표시 준비 완료. 전체 페이지 렌더 완료를 뜻하지 않습니다. |
onChange | (canvasData: string) => void | 편집 발생 시마다. 임시 저장·변경 감지에 사용. |
onSave | (canvasData: string, ok: boolean, msg: string) => void | save() 또는 내장 저장 버튼에 대한 응답. |
onClose | () => void | 뷰어 내 닫기 동작 발생 시. 호스트가 화면 전환을 처리. |
onError | (err: Error) => void | 통신 오류·콜백 내부 예외 발생 시. |
옵션 — 커스터마이징
네 가지 모두 커스터마이징 문서에 상세 명세가 있습니다.
| 옵션 | 타입 | 설명 |
|---|---|---|
theme | object | primaryColor · saveColor · historyColor · logoUrl · cssVars |
tools | object | enabled(편집 도구) · defaultTool(contentSelect 포함) · defaultColor · defaultWidth · features.search · features.bookmarks 등. contentSelect 버튼은 현재 enabled로 숨기지 않습니다. |
locale | string | 내장 'ko'(기본) · 'en' |
messages | object | UI 문구 키별 오버라이드 |
인스턴스 메서드
| 메서드 | 설명 |
|---|---|
loadPdfUrl(url, fileName?, canvasData?, readOnly?) | URL로 PDF 로드·교체. canvasData를 주면 해당 저장본이 복원된 채 열립니다. |
loadPdfBase64(base64, fileName?, canvasData?, readOnly?) | Base64로 PDF 로드·교체. 인자는 loadPdfUrl과 동일 구조. |
loadUserCanvasOverlay(list) | 다중 사용자·버전 레이어 주입. 항목 구조는 다중 사용자 레이어 참고. |
save() | 현재 편집 상태 직렬화 요청. 결과는 onSave 콜백으로 전달. |
exportPdf(): Promise<ArrayBuffer> | 지원하는 네이티브 AcroForm의 현재 값을 반영한 독립 PDF 바이트 반환. canvasData의 펜·형광펜·텍스트·도형 드로잉은 PDF에 합성하지 않습니다. |
applyConfig(config) | { theme?, tools?, locale?, messages? } 부분 갱신 — 전달한 키만 적용. |
clear() | 현재 페이지의 편집 캔버스 초기화. |
getLastCanvasData() | 마지막 onChange로 받은 canvasData 반환 (자동저장용 캐시). 변경이 없었다면 빈 문자열. |
isReady() | 뷰어 준비 완료 여부 — boolean. |
destroy() | iframe 제거·리스너 해제·내부 큐 폐기. SPA 화면 이탈 시 반드시 호출. |
iframe 속성 | 생성된 HTMLIFrameElement 참조 — 스타일 미세 조정 등 고급 용도. |
준비 전 호출은 자동 큐잉됩니다
isReady()가 false인 동안 호출된 명령(loadPdfUrl · save 등)은 내부 큐에 보관되어 뷰어 준비 직후 순서대로 실행됩니다.
타이밍 가드 코드를 작성할 필요가 없습니다.
Inko.MESSAGE_TYPES
SDK ↔ 뷰어 간 postMessage 타입 상수입니다. 일반 통합에서는 사용할 일이 없고, 통신 디버깅(개발자 도구에서 메시지 관찰)이나 SDK를 거치지 않는 직접 통합 같은 고급 시나리오에서 참조합니다.
| 상수 | 값 | 방향 |
|---|---|---|
LOAD_PDF_BASE64 | 'loadPdfBase64' | SDK → 뷰어 |
LOAD_PDF_FROM_URL | 'loadPdfFromUrl' | SDK → 뷰어 |
LOAD_USER_CANVAS | 'loadUserCanvasData' | SDK → 뷰어 |
SAVE_CANVAS | 'saveCanvas' | SDK → 뷰어 |
EXPORT_PDF | 'exportPdf' | SDK → 뷰어 |
CLEAR_CANVAS | 'clearCurrentCanvas' | SDK → 뷰어 |
APPLY_CONFIG | 'applyConfig' | SDK → 뷰어 |
VIEWER_READY | 'viewerReady' | 뷰어 → SDK |
PDF_LOADED | 'pdfLoaded' | 뷰어 → SDK |
CANVAS_CHANGED | 'canvasDataChanged' | 뷰어 → SDK |
SAVE_RESPONSE | 'saveCanvasResponse' | 뷰어 → SDK |
EXPORT_PDF_RESPONSE | 'exportPdfResponse' | 뷰어 → SDK |
CLOSE_VIEWER | 'closeViewer' | 뷰어 → SDK |
SET_ORIENTATION | 'setOrientation' | 뷰어 → SDK |
PDF 원문·검색·책갈피·AcroForm 범위
- 내용 선택 —
contentSelect모드는 PDF.js Text Layer가 만들어지는 PDF에서 원문 텍스트 선택·복사를 허용합니다. 이미지로만 된 PDF를 OCR로 변환하지 않습니다. - 검색 —
tools.features.search가false가 아니면 Ctrl/Cmd+F로 가상화된 화면 밖 페이지까지 Unicode 리터럴 검색을 수행합니다. 정규식·유사어·OCR 검색은 포함하지 않습니다. - 책갈피 —
tools.features.bookmarks가false가 아니고 PDF에 내장 outline이 있을 때만 중첩 목차와 페이지 이동 UI가 나타납니다. 책갈피 생성·편집 기능은 아닙니다. - 네이티브 양식 — 공개 fixture는 텍스트 필드·체크박스·선택 필드의 표시·입력·PDF 내보내기를 검증합니다. 읽기 전용 모드에서는 입력 컨트롤을 제공하지 않으며, 모든 AcroForm 유형이나 XFA 지원을 보장하지 않으므로 대상 PDF군에서 직접 확인해야 합니다.
canvasData와 PDF 바이트는 별도 저장 경로입니다
save()/onSave는 다시 편집할 Inko 드로잉 상태인 canvasData를 다룹니다. exportPdf()는 현재 네이티브 AcroForm 값이 반영된 PDF ArrayBuffer를 반환하지만
Inko 드로잉을 flatten하지 않습니다. 두 결과가 모두 필요하면 호스트 앱이 각각 저장해야 합니다.
보안 동작
- origin 검증 — SDK는
options.src에서 도출한 origin과 일치하는 메시지만 처리합니다. - source 검증 — 자신이 생성한 iframe에서 온 메시지만 수신합니다. 같은 페이지의 다른 iframe·브라우저 확장 메시지는 무시됩니다.
- 데이터 경로 — SDK 번들에는 PDF나 canvasData를 NextH 서버로 보내는 내장 엔드포인트가 없습니다. 실제 경로는 이용자가 지정한 PDF URL·저장 API·CDN·로그 구성에 따라 달라집니다.