Skip to main content
⚠️ 중요 안내 아래 테마 스니펫은 Upcart 카트 모듈의 두 버전 모두에 적용돼요 — 이 스니펫은 Shopify가 페이지에 가속 체크아웃 버튼을 렌더링하도록 만드는데, 모듈 버전과 관계없이 Upcart에 필요한 것이 바로 이거예요. 아래의 .additional-checkout-buttons 선택자는 Upcart 모듈 클래스가 아니라 가속 체크아웃 컨테이너에 대한 Shopify 자체 클래스이므로 어느 카트 버전에서든 동일해요.

​
개요

때때로 익스프레스 체크아웃 버튼이 클릭되지 않거나 Upcart 안에 나타나지 않는 경우가 있어요. 이는 Shopify가 테마 내에서 익스프레스 결제 버튼의 렌더링을 제어하는 방식 때문에 발생하는 흔한 문제예요. 이 가이드는 왜 이런 일이 발생하는지, 그리고 해결하려면 무엇을 해야 하는지 설명해요.

​
새 모듈에 필요한 설정

⚠️ 중요: 이 단계들은 레거시 버전이 아닌 Upcart의 새 Express Payments 모듈에 적용돼요. Upcart에서 익스프레스 체크아웃 버튼이 올바르게 작동하려면 Shopify 테마에 작은 코드 스니펫을 추가해야 해요. 이 스니펫이 없으면 Shopify가 카트 드로어 안에 결제 버튼을 제대로 로드하지 못해요. 변경하기 전에 관련 결제 수단(예: Shop Pay, PayPal, Apple Pay, Google Pay)이 Shopify 관리자 계정 설정에서 활성화되어 있는지 확인하세요. 이 수단들을 활성화하지 않으면 버튼이 보이지 않아요. 또한 스니펫이 테마 파일의 여는 <body> 태그(예: <body class="...">) 바로 아래에 배치되었는지 확인하세요. 닫는 </body> 태그 뒤처럼 잘못된 위치에 배치하면 익스프레스 체크아웃 버튼이 제대로 작동하지 않을 수 있어요.

​
해결 방법

  1. Shopify 관리자로 이동하세요.
  2. Online Store > Themes > Edit Code로 이동하세요.
  3. layout/theme.liquid를 열고 <body> 줄을 찾아 그 바로 아래 새 줄에 아래 스니펫을 추가하세요. 카트가 열릴 수 있는 모든 페이지에 버튼이 존재해야 하기 때문에, cart-drawer.liquid나 다른 곳이 아니라 반드시 여기에 넣어야 해요.
  1. 변경 사항을 저장하고 스토어프론트를 새로 고침하세요.
  2. 카트 드로어를 다시 열어 익스프레스 체크아웃 버튼(Shop Pay, PayPal, Apple Pay, Google Pay 등)이 이제 나타나고 클릭되는지 확인하세요.
전체 설정 안내는 Express Payments 모듈** 가이드**를 참고하세요.

​
발생 원인

익스프레스 결제 버튼은 Upcart가 아닌 Shopify가 전적으로 관리해요. 이는 다음을 의미해요:
  • Upcart는 자체 버튼을 렌더링하지 않아요. 페이지에 있는 Shopify의 가속 체크아웃 버튼을 카트 드로어로 복제하기 때문에 애초에 버튼이 페이지에 존재해야 하는데, 위의 테마 스니펫이 이를 보장해줘요.
  • Apple Pay는 Apple Pay가 설정된 Apple 기기에서만 표시돼요.
  • 콘텐츠와 기능을 Shopify가 처리하기 때문에 Upcart는 어떤 익스프레스 버튼이 나타나는지 제어하지 않아요.
🎨 참고:
Upcart의 버튼은 시각적 컨테이너 역할을 하며, 표시와 동작은 Shopify가 제어해요. Upcart는 버튼의 모양이나 기능을 수정할 수 없어요.

​
자주 발생하는 문제와 해결 방법

​
1. 페이지에 버튼이 렌더링되지 않는 경우

가장 흔한 원인이에요. Upcart는 페이지에서 Shopify의 버튼을 복제하기 때문에, 페이지가 버튼을 렌더링하지 않으면 복제할 대상이 없어 카트에 빈 공간이 표시돼요. 해야 할 일:
  • 위의 해결 방법에 있는 테마 스니펫을 layout/theme.liquid의 <body> 줄 바로 아래에 추가하세요.
“충돌을 피하기 위해” 테마 자체의 익스프레스 버튼을 제거하지 마세요. Upcart는 버튼이 존재하는 것에 의존해요. 테마에서 버튼을 제거하거나 테마 설정에서 끄면 Upcart가 복제할 원본이 사라져서 이 문제가 오히려 악화돼요.

​
3. CSS가 버튼을 차단하는 경우

일부 테마는 기본적으로 CSS를 사용해 익스프레스 버튼을 숨겨요. 예를 들어:
해야 할 일:
  • 테마의 CSS를 검토하세요.
  • Upcart 드로어에서 버튼을 숨기거나 비활성화하는 CSS 규칙이 없도록 테마 개발자에게 확인을 요청하세요.

​
4. 레거시 설정이 간섭하는 경우

Express Payments 모듈의 이전 버전을 사용했다면 저장된 설정이 새 설정과 충돌할 수 있어요. 해야 할 일:
  • (아직 보인다면) 이전 Express Payments 모듈을 여세요.
  • 이전 옵션들을 모두 선택 해제하고 저장하세요.
  • 새 모듈로 다시 테스트하세요.

​
여전히 문제가 있나요?

​
Upcart에서 Shadow DOM 비활성화하기

일부 경우에는 Upcart에서 Shadow DOM이 활성화되어 있어 익스프레스 결제 버튼이 로드되거나 업데이트되지 않을 수 있어요. Shadow DOM이란?
Shadow DOM은 안정성을 높이기 위해 Upcart를 스토어의 나머지 코드와 격리해요. 하지만 드물게 이 분리가 Shopify의 익스프레스 버튼이 올바르게 업데이트되는 것을 막을 수 있어요. Shadow DOM 비활성화 방법:
  1. Upcart > Cart Editor > Settings > Cart settings로 이동한 다음 Advanced Settings를 펼치세요.
  2. Render Cart in Shadow DOM을 선택 해제하세요.
  3. 저장하고 다시 테스트하세요.
⚠️ 중요:
Shadow DOM을 끈 후에는 다른 앱이나 테마 요소가 Upcart와 상호 작용하는 방식에 영향을 줄 수 있으므로 항상 카트를 테스트하세요. 💡 참고: Shadow DOM을 비활성화하면 이 문제가 해결될 수 있지만 테마와 CSS 충돌이 발생할 수 있어요. 전체 트레이드오프는 Shadow DOM 설정 문서를 참고하세요.

​
더 많은 도움이 필요하신가요?

이 단계를 완료한 후에도 문제가 지속되면:
  • 테마 개발자에게 연락하여 충돌하는 코드나 설정을 제거하도록 도움을 받으세요.
  • 고급 테마 편집이나 연동 지원이 필요하면 Shopify Expert에게 문의할 수도 있어요.

​
참고 자료

  • Shopify 도움말 – Accelerated Checkouts
  • Shopify 개발자 문서 – Express Payment Buttons