커스텀 위젯 — 브레이크포인트별 Figma 디자인 가이드

개요

하나의 커스텀 위젯에 PC / 태블릿 / 모바일 각각 다른 Figma 디자인을 등록할 수 있습니다. 방문자의 화면 크기에 따라 자동으로 적절한 디자인이 표시됩니다.

브레이크포인트 기준

디바이스	뷰포트 너비	필수 여부
PC	1024px 이상	필수
태블릿	800 ~ 1023px	선택 (미설정 시 PC 디자인 사용)
모바일	800px 미만	선택 (미설정 시 태블릿 → PC 순으로 폴백)

1. 커스텀 위젯 생성/편집

1-1. Figma 디자인 준비

Figma에서 각 디바이스용 프레임을 만듭니다.

디바이스	권장 프레임 너비
PC	1440px
태블릿	800px
모바일	375 ~ 437px

세 프레임 모두 같은 Figma 파일 안에 있어도 되고, 각각 다른 파일이어도 됩니다.

1-2. 디자인 가져오기

관리자에서 커스텀 > 새로 만들기 (또는 기존 위젯 편집)로 이동합니다.

세 개의 가져오기 섹션이 표시됩니다:

PC 디자인 (≥1024px)

[Figma URL 입력] [가져오기]

태블릿 디자인 (800~1023px)

선택사항 — 미설정 시 PC 디자인 사용

모바일 디자인 (<800px)

선택사항 — 미설정 시 태블릿→PC 폴백

가져오기 순서:

PC 디자인 — 반드시 먼저 가져오세요. CTA 버튼 감지가 PC 디자인 기준으로 동작합니다.
태블릿 디자인 — 선택사항. 태블릿 전용 레이아웃이 있을 때만 설정합니다.
모바일 디자인 — 선택사항. 모바일 전용 레이아웃이 있을 때만 설정합니다.

1-3. Figma URL 복사 방법

Figma에서 원하는 프레임을 선택합니다.
우측 패널에서 프레임이 선택된 상태에서 브라우저 주소창의 URL을 복사합니다.
URL에 ?node-id= 파라미터가 포함되어 있어야 합니다.

https://www.figma.com/design/ABC123/MyDesign?node-id=1-234

1-4. CTA 버튼 설정

PC 디자인에서 감지된 버튼에 대해 CTA 액션을 설정합니다:

URL 이동 — 지정한 URL로 새 탭 열기
쿠폰 복사 — 클립보드에 코드 복사
전화 걸기 — 전화번호로 연결

CTA 설정은 모든 브레이크포인트에서 공통으로 적용됩니다.

1-5. 미리보기

우측 미리보기에서 PC / Tablet / Mobile 토글로 각 디바이스별 표시를 확인합니다.

1-6. 저장

생성 (또는 저장) 버튼을 클릭하면 embed 스크립트가 표시됩니다.

2. Embed 스크립트 설치

저장 후 표시되는 스크립트 태그를 복사합니다:

<script src="https://biz.pyrocnc.co.kr/embed/loader.min.js?siteId=YOUR_SITE_ID&widgetId=YOUR_WIDGET_ID" defer></script>

이 하나의 스크립트가 방문자 화면 크기를 감지하여 자동으로 적절한 디자인을 표시합니다.

3. 쇼피파이 (Shopify) 설치 방법

방법 A: 테마 코드에 직접 삽입 (전체 페이지)

Shopify 관리자 > 온라인 스토어 > 테마 로 이동
현재 테마의 ... > 코드 편집 클릭
Layout 폴더에서 theme.liquid 파일을 엽니다
</body> 태그 바로 위에 스크립트를 붙여넣습니다:

    <!-- PopupHub 커스텀 위젯 -->
    <script src="https://biz.pyrocnc.co.kr/embed/loader.min.js?siteId=YOUR_SITE_ID&widgetId=YOUR_WIDGET_ID" defer></script>
  </body>
</html>

저장 클릭

theme.liquid에 넣으면 스토어 전체 페이지에서 팝업이 표시됩니다.

방법 B: 특정 페이지에만 표시

Shopify 관리자 > 온라인 스토어 > 테마 > 코드 편집
Templates 또는 Sections 폴더에서 원하는 페이지 템플릿을 엽니다

메인 페이지: index.liquid 또는 index.json
상품 페이지: product.liquid
컬렉션 페이지: collection.liquid

해당 파일의 맨 아래에 스크립트를 붙여넣습니다
저장 클릭

방법 C: 커스텀 Liquid 블록 (Shopify 2.0 테마)

Shopify 관리자 > 온라인 스토어 > 테마 > 커스터마이즈
원하는 섹션에서 블록 추가 > 커스텀 Liquid 선택
스크립트 태그를 입력합니다:

<script src="https://biz.pyrocnc.co.kr/embed/loader.min.js?siteId=YOUR_SITE_ID&widgetId=YOUR_WIDGET_ID" defer></script>

저장 클릭

4. 카페24 (Cafe24) 설치 방법

방법 A: 전체 페이지에 적용

카페24 관리자 > 디자인 > 디자인 편집 으로 이동
좌측 파일 목록에서 layout 폴더의 basic_layout.html 을 엽니다
</body> 태그 바로 위에 스크립트를 붙여넣습니다:

    <!-- PopupHub 커스텀 위젯 -->
    <script src="https://biz.pyrocnc.co.kr/embed/loader.min.js?siteId=YOUR_SITE_ID&widgetId=YOUR_WIDGET_ID" defer></script>
</body>
</html>

저장 클릭

basic_layout.html에 넣으면 쇼핑몰 전체 페이지에서 팝업이 표시됩니다.

방법 B: 특정 페이지에만 표시

카페24 관리자 > 디자인 > 디자인 편집
좌측 파일 목록에서 원하는 페이지 파일을 엽니다:

메인 페이지: main.html
상품 상세: product/detail.html
상품 목록: product/list.html
이벤트 페이지: board/event.html

파일 내용 맨 아래에 스크립트를 붙여넣습니다
저장 클릭

방법 C: 스마트디자인 앱 사용

카페24 관리자 > 디자인 > 디자인 편집
상단 스마트디자인 편집 모드로 전환
원하는 영역을 클릭 > HTML 편집
적절한 위치에 스크립트를 붙여넣습니다
저장 클릭

5. 폴백 동작

모든 브레이크포인트를 설정하지 않아도 됩니다. 미설정 시 다음 순서로 폴백합니다:

모바일 → 태블릿 → PC

설정 상태	PC 화면	태블릿 화면	모바일 화면
PC만 등록	PC 디자인	PC 디자인	PC 디자인
PC + 모바일	PC 디자인	PC 디자인	모바일 디자인
PC + 태블릿	PC 디자인	태블릿 디자인	태블릿 디자인
전부 등록	PC 디자인	태블릿 디자인	모바일 디자인

6. 주의사항

스크립트는 하나만 삽입하세요. 브레이크포인트 전환은 스크립트 내부에서 자동 처리됩니다.
PC 디자인을 반드시 먼저 등록하세요. CTA 버튼 감지가 PC 디자인 기준입니다.
Figma 토큰 설정이 필요합니다. 관리자 > 설정에서 Figma Personal Access Token을 등록해야 합니다.
기존 위젯과 호환됩니다. 브레이크포인트를 설정하지 않은 기존 커스텀 위젯은 이전과 동일하게 동작합니다.
스크립트 위치: </body> 바로 위에 넣는 것을 권장합니다. <head> 안에 넣어도 defer 속성 덕분에 동작하지만, 페이지 렌더링 이후 실행되는 </body> 위치가 가장 안정적입니다.