레퍼런스

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 구성이 단순해집니다. 폐쇄망·내부망에서도 실제 응답 헤더와 브라우저 정책을 확인하세요.

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

현재 검증 기준은 호스트 페이지와 같은 origin의 하위 경로 배포입니다. 별도 도메인 구성은 프로젝트별 호환성 검증이 필요하며, 최소한 다음 항목을 함께 확인해야 합니다:

뷰어 서버: 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가 얼마나 커질 수 있나요?

고정된 크기나 상한을 제시하지 않습니다. 페이지 수·편집 객체 수·펜 획의 포인트 수에 따라 커지므로, 실제 문서와 대상 기기에서 저장 크기·직렬화 시간·전송 시간을 측정하세요. DB 컬럼은 길이 제한 없는 TEXT 계열을 사용하고, API 요청 본문 크기 제한(예: Nginx client_max_body_size)을 함께 점검하세요.

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

SDK 번들에는 PDF나 canvasData를 NextH 서버로 보내는 내장 엔드포인트가 없습니다. 다만 실제 데이터 경로는 이용자가 지정한 PDF URL, 저장 API, CDN, 로그·모니터링 구성에 따라 달라집니다. 폐쇄망 적용 시에도 해당 구성과 브라우저 정책을 함께 검증해야 합니다.

오픈소스 라이선스 · 운영 책임

어떤 조건으로 사용할 수 있나요?

Inko는 Apache-2.0 무료 오픈소스입니다. 사용·수정·재배포 조건은 LICENSE가 정합니다. 소스는 GitHub, 배포 패키지는 npm에서 확인하세요.

설치와 유지보수는 누가 담당하나요?

이용자가 설치·연동·대상 환경 검증·업데이트·보안 패치 적용·포크 유지보수를 직접 담당합니다. NextH는 개별 기술지원, 응답 기한, SLA, LTS를 제공하지 않으며 호환성이나 운영 결과를 보증하지 않습니다. 이슈와 기여 제안의 응답·검토·수락·해결 또는 기한도 약속하지 않습니다.