레퍼런스

FAQ · 트러블슈팅

통합 과정에서 자주 묻는 질문과 해결 방법입니다. 여기에 없는 문제는 기술 문의로 보내주시면 엔지니어가 직접 답변합니다.

뷰어 영역이 비어 있게 나옵니다

컨테이너 높이를 확인하세요

가장 흔한 원인입니다. 뷰어 iframe은 기본적으로 컨테이너의 100% 크기를 차지하므로, 컨테이너 높이가 0이면 아무것도 보이지 않습니다.

컨테이너 높이 html

<!-- 잘못된 예 — 높이가 0이라 뷰어가 보이지 않음 -->
<div id="pdf-container"></div>

<!-- 올바른 예 — 명시적 높이 -->
<div id="pdf-container" style="width:100%; height:80vh"></div>

<!-- 또는 부모 체인 전체에 높이가 있는 경우 height:100% -->

X-Frame-Options / CSP가 임베드를 차단하는 경우

콘솔에 Refused to display ... in a frame 오류가 보이면, 뷰어 파일(/pdfv/)을 서빙하는 서버의 응답 헤더가 iframe 임베드를 막고 있는 것입니다. 같은 도메인 임베드는 SAMEORIGIN이면 충분합니다.

Nginx 헤더 설정 nginx

# Nginx — 같은 사이트 내 iframe 임베드 허용 (권장 설정)
location /pdfv/ {
  add_header X-Frame-Options "SAMEORIGIN";
  # CSP를 쓰는 경우:
  add_header Content-Security-Policy "frame-ancestors 'self'";
}

# 다른 도메인의 호스트 페이지에서 임베드해야 한다면:
# add_header Content-Security-Policy "frame-ancestors https://erp.example.com";

크로스 도메인 관련

pdfUrl이 다른 도메인일 때 PDF가 로드되지 않습니다

PDF 요청은 뷰어 iframe(브라우저)에서 발생하므로, PDF 서버가 다른 도메인이라면 해당 서버에 CORS 허용 헤더가 필요합니다.

PDF 파일 서버 CORS nginx

# PDF 파일 서버가 뷰어와 다른 도메인인 경우에만 필요
# (Same-Origin Sub-Path 배포 시에는 불필요)
location /files/ {
  add_header Access-Control-Allow-Origin "https://viewer-host.example.com";
}

가장 간단한 해법은 같은 도메인입니다

뷰어(/pdfv/)와 PDF 파일을 호스트 페이지와 같은 도메인에 두면 CORS·frame-ancestors 설정이 전혀 필요 없습니다. 폐쇄망·내부망 환경에서도 동일합니다.

뷰어를 별도 도메인에 두고 싶습니다

가능합니다. src에 절대 URL(예: https://viewer.example.com/pdfv/index.html)을 지정하면 SDK가 해당 origin을 기준으로 postMessage를 검증합니다. 이 경우 두 가지를 설정하세요:

뷰어 서버: frame-ancestors에 호스트 페이지 도메인 허용
PDF 서버: 뷰어 도메인에 대한 CORS 허용 (PDF가 또 다른 도메인인 경우)

자주 만나는 오류

증상	원인	해결
`target not found: #pdf-container`	컨테이너 요소가 생성되기 전에 `mount()` 호출	`mount()`를 DOM 준비 후(스크립트를 컨테이너 아래 배치, 또는 `DOMContentLoaded`)에 호출
`options.src (viewer URL) is required`	`src` 옵션 누락	배포한 뷰어 본체 URL을 `src`에 지정
저장했는데 `onSave`가 호출되지 않음	마운트 옵션에 `onSave` 미등록	`mount()` 옵션에 `onSave` 콜백 등록 — 응답은 항상 이 콜백으로만 옵니다
이전 작업이 복원되지 않음	`initialCanvasData` 미전달 또는 다른 문서의 값 전달	해당 문서의 최신 canvasData를 조회해 전달 — 이어서 편집 참고
SPA에서 화면을 오갈수록 동작이 중복됨	이탈 시 `destroy()` 누락으로 리스너 누적	컴포넌트 언마운트 시 `viewer.destroy()` 호출

데이터 관련

canvasData가 얼마나 커질 수 있나요?

편집량에 비례합니다. 일반적인 검토·서명 사용에서는 수십 KB 수준이지만, 페이지 전반에 걸친 자유 필기가 많으면 수 MB까지 커질 수 있습니다. DB 컬럼은 길이 제한 없는 TEXT 계열을 사용하고, API 요청 본문 크기 제한(예: Nginx client_max_body_size)을 함께 점검하세요.

문서가 외부로 전송되나요?

아니요. PDF와 canvasData는 호스트 페이지와 뷰어 iframe 사이에서만 오갑니다. SDK에는 외부 서버 호출 코드가 없으며, 저장 위치는 전적으로 고객사 시스템입니다. 폐쇄망에서도 동일하게 동작합니다.

라이센스 · 지원

라이센스는 어떻게 구성되나요?

1회성 구매 영구 라이센스이며 Starter · Business · OEM 3개 등급으로 제공됩니다. 등급별 사용 범위와 견적은 라이센스 안내에서 확인하거나 견적 문의로 연락 주세요.

기술 지원은 어떻게 받나요?

통합 단계의 기술 질문은 계약 시 안내된 지원 채널 또는 문의 양식으로 보내주세요. 재현 가능한 코드 조각과 브라우저 콘솔 로그를 함께 보내주시면 가장 빠르게 답변드릴 수 있습니다.