# 앱 마켓플레이스에서 웹 위젯 판매를 위한 개발자 가이드
이 가이드는 개발자가 퍼널 빌더에서 사용할 커스텀 위젯을 만들고 원활하게 통합하는 방법을 안내합니다. HTML, CSS, JavaScript 또는 Angular, React, Vue 등의 JS 프레임워크를 사용하여 커스텀 위젯을 생성, 설정, 렌더링하는 방법과 커스텀 위젯 애플리케이션과 퍼널 빌더 간의 통신을 다룹니다.
**목차**
* [사전 요구사항](#사전-요구사항)
* [개요](#개요)
* [단계별 가이드](#단계별-가이드)
* [1단계: 앱 마켓플레이스에서 개발자 등록](#1단계-앱-마켓플레이스에서-개발자-등록)
* [2단계: 커스텀 위젯 설정](#2단계-커스텀-위젯-설정)
* [3단계: 퍼널 빌더와 통합](#3단계-퍼널-빌더와-통합)
* [4단계: 애플리케이션과 퍼널 빌더 간 통신](#4단계-애플리케이션과-퍼널-빌더-간-통신)
* [✅ 지원되는 업로드 형식](#✅-지원되는-업로드-형식)
* [❌ .rar 또는 기타 형식](#❌-rar-또는-기타-형식)
* [모범 사례](#모범-사례)
***
## 사전 요구사항
* HTML, CSS, JavaScript 기본 지식 또는 JS 프론트엔드 프레임워크(Angular, React, Vue 등) 사용 경험
* iFrame에 대한 이해
* 이벤트 기반 프로그래밍에 대한 이해
***
## 개요
커스텀 위젯을 사용하면 가격 배너나 기타 인터랙티브 구성 요소와 같은 커스텀 요소를 삽입하여 퍼널 빌더의 기능을 확장할 수 있습니다.
***
## 단계별 가이드
### 1단계: 앱 마켓플레이스에서 개발자 등록
* 앱 마켓플레이스에서 개발자로 가입하세요.
* '앱 만들기(Create App)'를 클릭하고 앱 생성 여정을 시작하세요.
### 2단계: 커스텀 위젯 설정
**애플리케이션 생성**
사용자가 UI 요소와 상호작용하고 선택한 설정에 따라 커스텀 위젯 요소를 렌더링할 HTML, CSS, JS(필요한 경우)를 생성할 수 있는 독립적인 웹 애플리케이션을 개발하세요.
* 애플리케이션은 HTML, CSS, JS를 생성하는 다음 함수들을 가져야 합니다:
`createHtml()` => 위젯의 HTML 코드를 반환
`createJS()` => 웹사이트에서 위젯이 실행되는 데 필요한 JS 코드를 반환 (선택사항)
`createCss()` => 위젯 스타일에 필요한 CSS 코드를 반환
애플리케이션은 퍼널 빌더와 iFrame 통신을 위해 postmate를 사용해야 합니다. 위젯 코드는 이벤트 emit을 통해 퍼널 빌더로 전송될 수 있습니다.
예시:
```javascript
parent?.emit('code', {
html: html as string,
js: js as string,
elementStore: elementSettings as Object
})
```
매개변수:
**html**: 스타일과 함께 위젯을 렌더링하는 데 필요한 HTML 콘텐츠
예시:
```html
{여기에 HTML 콘텐츠가 들어갑니다}
```
**js**: 위젯이 실행되는 데 필요한 JS 코드 (선택사항)
참고: js 코드를 `` 태그로 감싸지 마세요
참고: JS 기반 애플리케이션인 경우, 다음 섹션에서 명시된 퍼널/웹사이트 팝업 또는 기타 JS 이벤트와 상호작용하는 데 필요한 모든 코드가 부모에게 전송되는 JS에 포함되어야 합니다.
**elementStore**: 위젯 설정을 나타내는 모든 변수 (변수명은 원하는 대로 지정 가능)
예시:
```javascript
settings: {
widgetHeight: number,
widgetWidth: number,
image: string
}
```
* 애플리케이션 초기화 또는 초기 핸드셰이크 시, 다음 페이로드를 기대하세요:
```javascript
{ elementStore: Object } // 코드를 부모에게 전송할 때 애플리케이션에서 전송한 elementStore입니다. 퍼널 빌더에서 사용자가 위젯에 대해 이미 저장한 설정을 미리 채우는 데 사용하세요.
```
그리고 미리보기의 초기 상태를 emit해야 합니다:
```javascript
parent?.emit('code', {
html: html as string,
js: js as string,
elementStore: elementSettings as Object
})
```
참고: 초기 상태를 emit해야 합니다. 받은 데이터가 위젯의 모든 해당 설정에 채워져서 재방문 시 이전에 저장된 값을 표시할 수 있도록 하세요.
### 3단계: 퍼널 빌더와 통합
1. **마켓플레이스에 업로드**
* 프로젝트를 빌드하고 HTML, CSS, JS 파일 또는 dist 폴더를 zip 파일로 마켓플레이스 앱에 업로드하세요
* 플랫폼의 가이드라인과 제출 요구사항을 준수하는지 확인하세요
⚠️ 빌드 시 절대 경로 사용을 피하고 프로젝트에서 상대 경로를 사용하세요.
```
apps/
│
├── app1/
│ ├──index.html
│ ├──css/
│ │ └── style.css
│ └──js/
│ └── script.js
│
└── app2/
├──index.html
├──css/
│ └── style.css
└──js/
└── script.js
```
index.html에서:
* 절대 경로: `css/style.css` (이를 피하세요)
* 상대 경로: `./css/style.css`
2. **퍼널 요소에 커스텀 위젯 추가**
* 승인되어 마켓플레이스에서 사용 가능해지면, 퍼널 빌더는 "커스텀 위젯(Custom Widgets)" 또는 유사한 섹션에 위젯을 나열합니다
* 사용자는 마켓플레이스에서 커스텀 위젯을 설치할 수 있습니다
* 퍼널 빌더로 위젯을 드래그 앤 드롭하세요
3. **제한된 설정 구성**
* 퍼널 빌더의 설정 영역에서 직접 편집할 수 있도록 제한된 설정(여백, 패딩, 가시성, 커스텀 클래스 등)을 구성하세요
* 주요 위젯 설정은 애플리케이션에서 처리하는 외부 팝업을 통해 구성되어야 합니다
4. **위젯 렌더링**
* 퍼널 빌더가 생성된 HTML, CSS, JavaScript를 해석하여 위젯을 렌더링할 수 있도록 하세요
### 4단계: 애플리케이션과 퍼널 빌더 간 통신
**iFrame 사용**
* 퍼널 빌더 내의 iframe에서 설정 애플리케이션을 호스트하세요(호스팅은 자동 처리됩니다)
* 설정이 조정될 때 HTML, CSS, JS 코드를 생성하고 통신하는지 확인하세요
**5단계: 이벤트 및 JS 통합**
커스텀 위젯 이벤트를 통해 커스텀 위젯이 퍼널 미리보기 환경과 통신할 수 있습니다. 이 통신은 위젯의 동작이 퍼널 미리보기에서 응답을 트리거할 수 있는 인터랙티브 웹 애플리케이션을 만들어 더 매끄럽고 통합된 사용자 경험을 제공하기 위함입니다.
**주요 개념**
* **이벤트 발생**: 커스텀 위젯은 사용자가 버튼 클릭이나 설정 변경과 같은 상호작용을 할 때 신호(이벤트)를 보낼 수 있습니다
* **이벤트 처리**: 퍼널 미리보기는 이러한 신호를 듣고 팝업 열기나 퍼널의 다음 단계로 이동하는 등의 특정 작업을 수행합니다
**이벤트:**
1. **customWidgetOpenPopup**
설명: 이 이벤트는 미리보기 측에서 팝업을 여는 동작을 트리거합니다.
예시:
```javascript
var event = new Event('customWidgetOpenPopup');
window.dispatchEvent(event)
```
2. **customWidgetGoToNextStep**
설명: 이 이벤트는 퍼널/웹사이트에서 다음 단계/페이지로 이동하는 동작을 트리거합니다.
예시:
```javascript
var event = new Event('customWidgetGoToNextStep');
window.dispatchEvent(event)
```
프레임워크 라우터를 사용하는 경우, `createMemoryHistory`에서 사용하세요.
참고로 Vue Router Memory Mode를 확인하세요.
**CSS 참고사항**: 모바일 기기용 미디어 쿼리를 사용하는 경우, `.--mobile` 접두사가 있는 클래스를 대상으로 하여 퍼널 빌더 모바일 모드와의 호환성도 고려해야 합니다.
**예시: 마케팅 가격 배너 위젯**
github.com
**위젯 앱 검토 제출 전 체크리스트**
커스텀 위젯을 퍼널 빌더에 개발하고 통합할 때는 중단이나 충돌을 일으키지 않고 효과적으로 작동하는지 확인하는 것이 중요합니다. 앱 검토를 위해 제출하기 전에 이 체크리스트에 언급된 기준을 충족하는지 앱을 테스트해 주세요.
* **빌더 기능을 방해하지 않는지 확인**: 위젯이 원활하게 통합되고 퍼널 빌더의 핵심 기능을 방해하지 않는지 확인하세요
* **다른 요소와 충돌하지 않는지 확인**: 위젯이 빌더에 이미 있는 다른 요소와 겹치거나 방해하지 않아 시각적 또는 기능적 문제를 일으키지 않는지 확인하세요
* **외부 스크립트 확인**: 의도하지 않은 외부 스크립트가 위젯에 포함되지 않았는지 주의 깊게 확인하세요. 특히 그러한 포함이 의도되지 않은 경우에는 더욱 그렇습니다. 이는 보안 위험이나 기능 충돌을 일으킬 수 있습니다
* **화이트 라벨 프로세스를 방해하지 않는지 확인**: 애플리케이션이 화이트 라벨링을 지원하는 경우, 위젯이 이 기능을 유지하고 실수로 브랜드별 세부 정보를 노출하지 않는지 확인하세요
* **앱 상태가 일관되고 지속적인지 확인**: 위젯이 다양한 상호작용과 재방문에서 상태를 유지하여 일관된 사용자 경험을 보장하는지 확인하세요
* **초기 상태가 올바르게 표시되는지 확인**: 로드 시 위젯이 의도한 대로 초기 상태를 정확히 반영하고 모든 사전 정의된 설정과 구성을 표시하는지 확인하세요
* **모든 설정이 제대로 작동하는지 테스트**: 위젯 내의 각 구성 가능한 설정을 검토하여 버그나 예상치 못한 동작 없이 예상대로 작동하는지 확인하세요
이러한 각 항목을 신중히 검토하여 퍼널 빌더 환경에서 커스텀 위젯의 품질과 신뢰성을 보장할 수 있습니다. 이 체크리스트는 배포 전에 잠재적 문제를 찾는 품질 보증 도구 역할을 합니다.
***
HighLevel의 앱 마켓플레이스에서 웹 위젯 판매를 위한 개발자 가이드에 따르면, 특정 가이드라인에 따라 파일을 업로드하는 옵션이 있습니다:
#### ✅ 지원되는 업로드 형식
다음 사항이 필요합니다:
* 위젯 프로젝트(HTML, CSS, JS)를 빌드하세요
* .zip 파일로 번들링하세요(.rar 아님)
* 위젯 설정 과정에서 앱 마켓플레이스에 .zip 파일을 업로드하세요
#### ❌ .rar 또는 기타 형식
* .RAR 파일은 지원되지 않습니다
* .zip만 허용되는 아카이브 형식으로 언급됩니다
#### 모범 사례
위젯을 만들 때:
* 애셋에 상대 경로를 사용하세요
* 빌드를 깔끔하게 유지하세요 — 불필요한 파일이나 폴더는 제외
* zip 압축 전에 HTML, CSS, JS가 올바른 디렉터리 구조에 있는지 확인하세요
React나 Vue와 같은 프론트엔드 프레임워크를 사용하는 경우, 전체 프로젝트 디렉터리가 아닌 build/dist 폴더를 zip으로 압축하세요.
***
*원문 최종 수정: Fri, 29 Aug, 2025 at 2:59 AM* *Hyperclass 사용 가이드 — hyperclass.ai*
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://hyperclass.gitbook.io/hyperclass-docs/developer/developer-guide-for-selling-web-widgets-on-the-app-marketplace.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.