표시 문제 해결(트러블슈팅)

스토어프론트에서 PDF가 표시되지 않을 때 자주 발생하는 문제와 해결 방법을 정리했습니다.

PDF가 전혀 표시되지 않음

아래 3가지를 확인하세요.

✅ PDF가 리소스(상품/페이지 등)에 연결(Link) 되어 있는지
✅ PDF 상태가 Active인지(Inactive가 아닌지)
✅ 테마에 Theme App Extension이 추가되어 있는지

세 가지가 모두 충족되어야 합니다. 아래 순서대로 확인하세요.

1. PDF 라이브러리를 엽니다.
2. 표시되어야 하는 PDF를 클릭합니다.
3. 올바른 리소스에 연결되어 있는지 확인합니다.
4. 상태가 Active인지 확인합니다.
5. 테마 편집기로 이동해 확장(Extension)이 추가되어 있는지 확인합니다.

매뉴얼 블록(PDF Embedded Manual, PDF Button Manual)을 사용 중이라면, 위의 “연결된 PDF” 체크는 적용되지 않습니다. 아래 매뉴얼 블록 체크 항목을 확인하세요.

매뉴얼 URL 블록에 아무것도 표시되지 않음

1. https://...pdf 형태의 유효한 URL이 최소 1개 입력되어 있는지 확인합니다.
2. 블록이 현재 사용 중인 상품 템플릿에 추가되어 있는지 확인합니다.
3. 테마 편집기에서 저장한 뒤, 스토어프론트를 강력 새로고침(hard refresh)합니다.
4. 커스텀 뷰어 파라미터 문제를 분리하기 위해, 뷰어 유형을 일시적으로 Native Browser로 바꿔 테스트합니다.
5. 버튼 라벨을 사용 중이라면, 라벨 줄 수가 URL 줄 수와 맞는지 확인합니다.

PDF가 잘못된 페이지에 표시됨

가능한 원인:

잘못된 리소스에 연결됨

• PDF가 어떤 리소스에 연결되어 있는지 확인합니다.
• 잘못된 리소스에서 연결을 해제(Unlink)합니다.
• 올바른 리소스에 다시 연결합니다.

템플릿 필터 불일치

• 템플릿 필터 설정을 확인합니다.
• 해당 페이지가 기대하는 템플릿을 사용 중인지 확인합니다.
• 필요하면 템플릿 필터를 제거하거나 조정합니다.

템플릿 필터링 알아보기 →

어떤 PDF는 보이는데, 일부만 보이지 않음

개별 PDF 상태 확인:

• 보이지 않는 PDF는 Inactive일 가능성이 높습니다.
• 해당 PDF를 Active로 변경하세요.

템플릿 필터 확인:

• 일부 PDF에 템플릿 필터가 적용되어 있을 수 있습니다.
• 표시되지 않는 PDF의 필터 설정을 검토하세요.

테마 편집기에서 Theme App Extension이 보이지 않음

테마 호환성 이슈:

사용 중인 테마가 app extensions를 지원하지 않을 수 있습니다.

1. 테마 문서에서 app extension 지원 여부를 확인합니다.
2. 가능하다면 테마를 최신 버전으로 업데이트합니다.
3. 필요하면 테마 개발자에게 지원을 요청합니다.
4. 확장(Extension) 호환 테마로 변경하는 것도 고려합니다.

대부분의 최신 Shopify 테마(2.0+)는 app extensions를 지원합니다.

PDF 로딩이 느림

파일 용량 최적화:

• 업로드 전에 PDF를 압축하세요.
• 가능하면 5MB 이하를 권장합니다.
• 불필요한 페이지/이미지를 제거하세요.

인터넷 연결 확인:

• 느린 네트워크에서는 로딩이 늦어질 수 있습니다.
• 다른 네트워크에서도 테스트해 보세요.
• 모바일 데이터와 Wi‑Fi에서 비교해 보세요.

버튼 표시 사용:

• 버튼 방식은 임베디드보다 빠르게 느껴질 수 있습니다.
• 고객이 클릭한 PDF만 로드합니다.
• 모바일 사용자에게 더 유리합니다.

임베디드 뷰어가 빈 화면으로 보임

PDF 파일이 손상되었을 수 있음:

• PDF를 다시 업로드해 보세요.
• 업로드 전에 컴퓨터에서 PDF가 정상 열리는지 확인하세요.
• 다른 소프트웨어로 다시 저장한 뒤 업로드해 보세요.

브라우저 호환성:

• 다른 브라우저에서 테스트해 보세요.
• 브라우저를 최신 버전으로 업데이트하세요.
• 브라우저 캐시를 삭제해 보세요.

잘못된 PDF가 표시됨

연결 상태 확인:

• 해당 PDF의 연결된 리소스 목록을 확인합니다.
• 표시되면 안 되는 페이지에서 연결을 해제(Unlink)합니다.
• 각 리소스에 올바른 PDF가 연결되어 있는지 확인합니다.

여러 PDF가 연결된 경우:

• 여러 PDF가 연결되어 있으면 모두 표시됩니다.
• 원치 않는 PDF는 연결을 해제하세요.
• 필요하면 순서를 조정하세요.

매뉴얼 블록을 사용 중이라면, 연결 상태 대신 테마 블록 설정의 URL 줄을 직접 확인하세요.

PDF 버튼을 눌러도 열리지 않음

JavaScript 이슈:

• 브라우저 콘솔에 오류가 있는지 확인합니다.
• 다른 브라우저에서 테스트해 보세요.
• 충돌할 수 있는 앱/확장 프로그램을 잠시 비활성화해 보세요.

테마 충돌:

• 일부 테마는 팝업을 제한할 수 있습니다.
• 테마 설정을 확인하세요.
• 필요하면 테마 개발자에게 문의하세요.

템플릿 필터링이 동작하지 않음

자주 하는 실수:

템플릿 이름이 잘못됨:

• 템플릿 이름은 대/소문자를 구분할 수 있습니다.
• 철자를 정확히 확인하세요.
• 테마에 해당 템플릿이 실제로 존재하는지 확인하세요.

템플릿이 적용되지 않음:

• 페이지가 다른 템플릿을 사용 중일 수 있습니다.
• 테마 편집기에서 실제 적용 템플릿을 확인하세요.
• 페이지에 올바른 템플릿을 할당하세요.

템플릿 관련 문제 해결 →

변경 사항이 반영되지 않음

캐시 지연:

• 변경 후 30~60초 기다립니다.
• 페이지를 새로고침합니다(강력 새로고침: Cmd/Ctrl + Shift + R).
• 필요하면 브라우저 캐시를 삭제합니다.

테마 저장 안 됨:

• 테마 편집기에서 Save를 눌렀는지 확인하세요.
• 저장되지 않은 변경 사항 표시가 있는지 확인하세요.

그래도 해결되지 않나요?

아래를 순서대로 시도해 보세요.

1. 전체 새로고침

   • 브라우저를 강력 새로고침합니다.
   • 테마 편집기에서 다시 저장합니다.
   • 몇 분 기다린 뒤 다시 확인합니다.

2. 시크릿(Incognito) 모드 테스트

   • 새 브라우저 세션으로 테스트합니다.
   • 캐시 영향을 줄일 수 있습니다.
   • 브라우저 확장 프로그램 영향 여부를 분리할 수 있습니다.

3. 다른 페이지에서도 확인

   • 다른 리소스(상품/페이지)에서도 확인합니다.
   • 홈페이지와 상품 페이지를 비교 테스트합니다.
   • 어느 조건에서만 문제가 발생하는지 범위를 좁힙니다.

4. 지원팀에 문의

   • 실제로 보이는 것과 기대한 동작을 함께 설명합니다.
   • 가능하면 스크린샷을 첨부합니다.
   • 사용 중인 테마 이름을 알려주세요.
   • 플랜 유형도 함께 알려주세요.

다음 단계

• 업로드 문제 해결
• 연결 문제 해결
• FAQ 보기