# 임베드

Source: https://docs.rooquiz.com/ko/publish/embed

> 퀴즈를 내 웹사이트에 직접 임베드해 방문자가 페이지를 떠나지 않고 응답하게 하는 방법을 설명합니다. 인라인, 팝업, 기본 iframe 세 가지 임베드 모드와 각 모드가 생성하는 코드, 사용할 수 있는 속성과 JS API, 페이지 유형별로 어떤 모드가 적합한지 안내합니다.

링크 공유 외에도 **퀴즈를 내 웹사이트에 직접 임베드**할 수 있습니다. 방문자는 랜딩 페이지를 떠나지 않고 퀴즈를 완료합니다.

## 세 가지 임베드 모드

대상 퀴즈에서 **공유** → **임베드**를 열고 표시 모드를 선택한 뒤, 생성된 코드를 사이트의 HTML에 복사해 넣습니다.

| 모드                    | 적합한 용도                | 동작                       |
| --------------------- | --------------------- | ------------------------ |
| **인라인 (높이 자동)**       | 페이지 콘텐츠 흐름에 자연스럽게 녹이기 | 높이가 콘텐츠에 맞춰 자동 조정됩니다. 권장 |
| **팝업**                | 페이지의 행동 유도 버튼         | 퀴즈를 전체 화면 오버레이로 엽니다      |
| **기본 iframe (고정 높이)** | 스크립트를 로드할 수 없는 환경     | 가장 단순함. 높이가 고정되고 내부 스크롤  |

### 인라인 (높이 자동)

```html
<div data-rooquiz-embed data-rooquiz-token="YOUR_QUIZ_TOKEN"></div>
<script src="https://YOUR_QUIZ_DOMAIN/embed.js" async></script>
```

임베드 스크립트는 퀴즈 콘텐츠의 높이 변화(페이지 넘김, 결과 페이지로 이동 등)를 감지해 iframe 크기를 실시간으로 조정합니다. 스크롤바도, 잘림도 없습니다.

### 팝업

```html
<div data-rooquiz-embed data-rooquiz-token="YOUR_QUIZ_TOKEN" data-rooquiz-mode="popup" data-rooquiz-text="Start the quiz"></div>
<script src="https://YOUR_QUIZ_DOMAIN/embed.js" async></script>
```

페이지에 버튼이 표시되고, 클릭하면 퀴즈가 전체 화면 오버레이로 열립니다. ESC 키를 누르거나 바깥 영역을 클릭하면 닫힙니다.

### 기본 iframe

```html
<iframe src="https://YOUR_QUIZ_DOMAIN/a/YOUR_QUIZ_TOKEN?embed=1" width="100%" height="600" style="border:0;" title="RooQuiz"></iframe>
```

iframe은 항상 사용자 지정 경로가 아닌 퀴즈의 고정 주소 `/a/<token>`을 가리킵니다. 따라서 나중에 사용자 지정 경로를 바꿔도 이미 사이트에 넣어 둔 임베드 코드는 깨지지 않습니다.

## "Made with RooQuiz" 문구

**Free 플랜**에서는 임베드에 작은 **Made with RooQuiz** 크레딧 문구가 남습니다. 이 문구는 **iframe 바깥**, 즉 내 페이지 위에 표시됩니다. 인라인 임베드와 팝업 임베드는 `embed.js`가 자동으로 렌더링하며, 기본 iframe 코드에는 iframe 바로 아래에 `<p>` 요소로 포함되어 있으니 그대로 두세요. **Pro**에서는 생성되는 코드에 이 문구가 들어가지 않습니다.

## 사용할 수 있는 속성

| 속성                          | 설명                                                                                                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-rooquiz-token`        | 필수. 퀴즈 공개 토큰                                                                                                                                                                                                                                      |
| `data-rooquiz-mode`         | `inline`(기본값) 또는 `popup`                                                                                                                                                                                                                          |
| `data-rooquiz-utm-source`   | 모든 응답과 함께 기록되는 UTM 소스. [UTM 유입 경로 추적](https://docs.rooquiz.com/ko/publish/tracking)과 [인사이트](https://docs.rooquiz.com/ko/results/insights)의 유입 경로별 분석에 사용됩니다                                                                                                                                       |
| `data-rooquiz-utm-medium`   | UTM 매체(선택)                                                                                                                                                                                                                                        |
| `data-rooquiz-utm-campaign` | UTM 캠페인(선택)                                                                                                                                                                                                                                       |
| `data-rooquiz-height`       | 인라인 모드의 초기 높이(px). 자동 크기 조정이 시작되기 전에 사용됩니다                                                                                                                                                                                                        |
| `data-rooquiz-text`         | 팝업 모드의 버튼 텍스트                                                                                                                                                                                                                                     |
| `data-rooquiz-track`        | `auto`: 페이지에 이미 설치된 Meta와 TikTok 픽셀도 함께 실행합니다([전환 이벤트](#전환-이벤트) 참고)                                                                                                                                                                               |
| `data-rooquiz-pass`         | 페이지 주소에서 퀴즈로 전달할 [URL 매개변수](https://docs.rooquiz.com/ko/publish/tracking)(쉼표 구분). 예: `partner,campaign_id`(`email,name`을 추가하면 리드 양식을 미리 채움). JS API에서는 `params: { partner: 'acme' }`로 값을 직접 전달할 수 있습니다 퀴즈의 URL 매개변수를 바꾼 뒤에는 임베드 코드를 다시 복사하세요. 사이트에 붙여 둔 코드는 이전 목록 그대로입니다. |

UTM 속성을 지정하지 않으면 호스트 페이지 URL에 있는 `utm_*` 매개변수가 자동으로 전달됩니다.

## 전환 이벤트

**Pro** 요금제에서는 인라인과 팝업 임베드가 퀴즈의 전환 이벤트(퀴즈 시작, 리드 확보, 퀴즈 완료, CTA 클릭 등)를 페이지로 전달합니다. 각 이벤트는 `rooquiz_<이벤트>`로 페이지의 `dataLayer`에 전달되고(내 Google 태그 관리자용), `rooquiz:<이벤트>`라는 브라우저 이벤트로도 발생합니다. `data-rooquiz-track="auto"`를 추가하거나 임베드 패널에서 **내 페이지의 Meta 및 TikTok 픽셀도 실행**을 켜면 페이지에 이미 설치된 픽셀로 바로 전송됩니다. JS API에서는 `track: 'auto'`를 전달하세요.

기본 iframe은 이벤트를 전달할 수 없습니다. 전체 이벤트 목록은 [광고 추적 픽셀](https://docs.rooquiz.com/ko/publish/ad-pixels)을 참고하세요.

## JS API

직접 디자인한 버튼으로 팝업을 여는 것처럼 사용자 지정 트리거가 필요하다면 API를 직접 호출하세요.

```html
<script src="https://YOUR_QUIZ_DOMAIN/embed.js"></script>
<script>
  // Mount an inline embed manually
  RooQuiz.embed({ el: '#container', token: 'YOUR_QUIZ_TOKEN', utmSource: 'homepage' })
  // Open the popup from any element
  document.querySelector('#my-button').onclick = () => RooQuiz.open('YOUR_QUIZ_TOKEN', { utmSource: 'homepage' })
</script>
```

<Callout type="info">
  임베드된 페이지는 푸터와 배경을 자동으로 숨겨 사이트에 투명하게 어우러지며, 테마 색상은 그대로 적용됩니다. 임베드로 수집한 응답도 평소처럼 [응답 기록](https://docs.rooquiz.com/ko/results/records)에 표시됩니다.
</Callout>
