# 網站嵌入

Source: https://docs.rooquiz.com/zh-TW/publish/embed

> 除了分享連結，你還可以把測驗直接嵌進自己的網站——訪客無需跳轉，在你的到達頁裡就能完成作答。這一頁介紹三種嵌入方式各自適合什麼位置與表現差異、生成的程式碼怎麼貼、可用的屬性有哪些，以及 JS API 能做什麼，方便你按頁面結構挑一種。嵌入後的作答與直接開啟連結算同一份資料，不同來源可以用 UTM 參數區分開。

除了分享連結,你還可以把測驗**直接嵌進自己的網站**——訪客無需跳轉,在你的到達頁裡就能完成作答。

## 三種嵌入方式

在目標測驗中開啟 **分享** → **網站嵌入**,選擇展示方式後複製生成的程式碼,貼上到你網站的 HTML 中即可。

| 方式                 | 適合場景       | 特點               |
| ------------------ | ---------- | ---------------- |
| **內嵌(自適應)**        | 融入頁面內容流    | 高度隨內容自動調整,推薦使用   |
| **彈出視窗**           | 頁面上放一個入口按鈕 | 點擊後以全螢幕彈出視窗開啟測驗  |
| **純 iframe(固定高度)** | 不便載入腳本的環境  | 最簡單,高度固定、內容在框內捲動 |

### 內嵌(自適應)

```html
<div data-rooquiz-embed data-rooquiz-token="你的测验代码"></div>
<script src="https://你的作答域名/embed.js" async></script>
```

嵌入腳本會自動監聽測驗內容的高度變化(翻頁、進入結果頁等),即時調整 iframe 高度,無捲軸、無截斷。

### 彈出視窗

```html
<div data-rooquiz-embed data-rooquiz-token="你的测验代码" data-rooquiz-mode="popup" data-rooquiz-text="开始测评"></div>
<script src="https://你的作答域名/embed.js" async></script>
```

頁面上會渲染一個按鈕,點擊後以全螢幕遮罩彈出視窗開啟測驗,支援 ESC 或點擊遮罩關閉。

### 純 iframe

```html
<iframe src="https://你的作答域名/a/你的测验代码?embed=1" width="100%" height="600" style="border:0;" title="RooQuiz"></iframe>
```

iframe 始終指向測驗穩定的 `/a/<token>` 位址，而不是自訂路徑，所以日後修改自訂路徑也不會讓已經放在你網站上的嵌入程式碼失效。

## 「Made with RooQuiz」標註行

在 **免費版** 上，嵌入內容會保留一行小小的 **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/zh-TW/publish/tracking)與[數據洞察](https://docs.rooquiz.com/zh-TW/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/zh-TW/publish/tracking)，以逗號分隔，例如 `partner,campaign_id`（加上 `email,name` 可預先填好留資表單）。使用 JS API 時可直接傳入 `params: { partner: 'acme' }` 改了測驗的 URL 參數後，請重新複製嵌入程式碼：已經貼在網站上的程式碼仍是舊的參數清單。 |

如果沒有設定 UTM 屬性,宿主頁面網址上的 `utm_*` 參數會自動透傳。

## 轉換事件

**Pro** 團隊的內嵌和彈出視窗嵌入會把測驗的轉換事件——開始作答、留資、完成作答、點擊 CTA 等——轉給你的網頁：每個事件以 `rooquiz_<事件>` 推進網頁的 `dataLayer`（給你自己的 GTM 使用），同時派發名為 `rooquiz:<事件>` 的瀏覽器事件。加上 `data-rooquiz-track="auto"`，或在嵌入面板裡開啟 **同時觸發我網頁上的 Meta 和 TikTok 像素**，事件就會直接發給你網頁上已安裝的像素。使用 JS API 時傳入 `track: 'auto'`。

純 iframe 無法轉發事件。完整事件清單見[廣告追蹤像素](https://docs.rooquiz.com/zh-TW/publish/ad-pixels)。

## JS API

需要自訂觸發時機(比如用你自己設計的按鈕開啟彈出視窗),可以直接呼叫:

```html
<script src="https://你的作答域名/embed.js"></script>
<script>
  // 手动挂载内嵌
  RooQuiz.embed({ el: '#container', token: '你的测验代码', utmSource: 'homepage' })
  // 用任意元素触发弹窗
  document.querySelector('#my-button').onclick = () => RooQuiz.open('你的测验代码', { utmSource: 'homepage' })
</script>
```

<Callout type="info">
  嵌入頁面會自動隱藏頁尾與背景,以透明形態融入你的網站;主題色仍然生效。嵌入帶來的作答會照常出現在[答卷記錄](https://docs.rooquiz.com/zh-TW/results/records)中。
</Callout>
