레퍼런스
API 레퍼런스
Inko SDK의 전체 공개 API 명세입니다. 사용 흐름 중심의 설명은 시작하기와 핵심 가이드 문서를 참고하세요.
전역 객체
전역 API js
// <script src="/pdfv/sdk/pdfv-sdk.js"> 로드 후
window.Inko // 권장 전역 이름
window.PdfViewer // 동일 객체의 별칭 (하위 호환)
Inko.mount(target, options) // 뷰어 마운트 → 인스턴스 반환
Inko.version // SDK 버전 문자열 — '1.0.0'
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) — 그 시점부터 이어서 편집. SDK는 값을 해석하지 않고 그대로 전달합니다. |
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 렌더 완료. 레이어 주입·로딩 UI 제거에 적합. |
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 · defaultColor · defaultWidth · features |
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 콜백으로 전달. |
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 → 뷰어 |
CLEAR_CANVAS | 'clearCurrentCanvas' | SDK → 뷰어 |
APPLY_CONFIG | 'applyConfig' | SDK → 뷰어 |
VIEWER_READY | 'viewerReady' | 뷰어 → SDK |
PDF_LOADED | 'pdfLoaded' | 뷰어 → SDK |
CANVAS_CHANGED | 'canvasDataChanged' | 뷰어 → SDK |
SAVE_RESPONSE | 'saveCanvasResponse' | 뷰어 → SDK |
CLOSE_VIEWER | 'closeViewer' | 뷰어 → SDK |
보안 동작
- origin 검증 — SDK는
options.src에서 도출한 origin과 일치하는 메시지만 처리합니다. - source 검증 — 자신이 생성한 iframe에서 온 메시지만 수신합니다. 같은 페이지의 다른 iframe·브라우저 확장 메시지는 무시됩니다.
- 데이터 경로 — PDF와 canvasData는 호스트 페이지 ↔ 뷰어 iframe 사이에서만 오가며, SDK가 외부 서버로 전송하는 데이터는 없습니다.