> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/zh-tw/configuration/section-banners.md).

# 區段橫幅

只要將資料檔放入建置成果中，就能在首頁任何區塊下方顯示促銷或贊助橫幅——不用改程式、不用提交，適用於任何部署。

每個首頁區塊都會以一個固定的橫幅插槽作結 —— 一張資訊風格的卡片，包含標題、說明，以及一個行動呼籲按鈕（`frontend/components/widgets/InfoBanner.vue`）。插槽中顯示什麼（如果有的話），完全由資料決定：每個區塊在 `frontend/data/banners/`.

該目錄為 **被 git 忽略**。新複製下來的專案在任何地方都不會顯示橫幅；在部署環境放入一個檔案， *是* 就決定在那裡顯示該橫幅。這使得此功能屬於部署設定，而不是產品程式碼：官方網站與任何分支都使用完全相同的機制，而行銷文案從不碰觸語系套件或 git 歷史。

{% hint style="info" %}
不同於列在 [與 IPCheck.ing 綁定的功能](/developer/zh-tw/configuration/features-tied-to-ipcheck-ing.md)中的工具，橫幅沒有 **沒有** `originalSite` 門檻。部署位置是唯一的門檻——自架實例只要一個資料檔就能運行自己的橫幅。
{% endhint %}

兩種典型用途：

* **自我推廣** ——將某個區塊指向內建工具，並使用內部的 `到` 目標。官方網站的 DNS 洩漏區塊就是這樣做，以顯示深度 DNS 洩漏測試。
* **贊助商** ——指向外部登陸頁，並搭配 `url`，並讓內建的 UTM 處理將流量歸因。

## 這六個插槽

插槽元件永久固定在每個區塊底部； `區塊` prop 會對應到資料檔名。大多數區塊也會把一個「settled」訊號傳給插槽——也就是它們自己的 *測試已完成完整一輪* 旗標——而橫幅預設會等待這個旗標（見 `requireSettled` 下方）。

| `區塊`        | 首頁區塊      | 何時算 settled           |
| ----------- | --------- | --------------------- |
| `ipinfo`    | IP 卡片     | 每張可見的 IP 卡片都已 settled |
| `連線性`       | 連線性       | 完整檢查一輪已 settled       |
| `webrtc`    | WebRTC 測試 | STUN 測試已完成解析          |
| `dnsleak`   | DNS 洩漏測試  | 首頁測試已完成解析（成功或逾時）      |
| `speedtest` | 速度測試      | 一次速度測試執行已完成           |
| `進階`        | 進階工具      | 立即——卡片網格不執行任何測試       |

## 資料檔

`frontend/data/banners/<section>.js` ——檔名就是插槽。該檔案預設匯出下列其中之一： `null` （明確關閉插槽）或 **一個** 純物件，且沒有任何 import，因此純 Node 測試執行器也能載入。標準契約位於以下檔案的標頭註解中： `frontend/utils/banners.js`；如果此頁面與程式碼日後出現偏差，就以那裡作為參考。

{% code title="frontend/data/banners/ipinfo.js" %}

```js
export default {
    id: 'vps',                   // unique across all banner files
    icon: 'Server',              // lucide icon name (string)
    track: 'IPInfoVPS',          // campaign id — the analytics label
    copy: {
        en: { title: 'Fast VPS', note: 'One-line pitch.', cta: 'Get it' },
        zh: { title: '高速 VPS', note: '一句話說明。', cta: '立即獲取' },
    },
    // Click target — exactly ONE of `url` (external) or `to` (internal):
    url: 'https://sponsor.example.com/deal',
    utm: { source: 'ipcheck.ing', medium: 'referral', campaign: 'ipinfo-vps' },
};
```

{% endcode %}

| 欄位               | 必填            | 意義                                                                                                                                                    |
| ---------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | 是             | 在部署上的所有橫幅檔案中必須唯一                                                                                                                                      |
| `icon`           | 是             | 一個 lucide 圖示 **名稱** 作為字串。元件會將它映射到匯入的圖示；字典為 `Globe`, `Megaphone`, `Server`, `Shield`, `Sparkles`, `Zap`，未知名稱會退回為 `Megaphone`。名稱保持為字串，因此資料檔不需要 import   |
| `track`          | 是             | 活動 ID —— 會成為點擊事件上的標籤（見下方 Analytics）                                                                                                                   |
| `copy`           | 是             | 依 UI 語系代碼索引的內嵌文案對照表： `{ en: { title, note, cta }, <code>?: { … } }`英文是必填且完整的；其他語系皆為可選，並會直接回退到英文——這個對照表只是單純查表，不是語系回退鏈。文案屬於每個活動的資料 **設計上** ——絕不使用語系套件鍵名 |
| `url`            | 兩者之一          | 外部目標：會在新分頁開啟，並附加 UTM 參數                                                                                                                               |
| `utm`            | 否（`url` 僅）    | UTM 歸因，鍵名 **沒有** 會以 `utm_` 前綴（`{ source, medium, campaign }`）。這個輔助函式會加上前綴並附加 `utm_content=<lang>` ——訪客的語系——如此一來活動就能看出是哪個語言介面轉換。現有的查詢參數會在 `url` 上被保留   |
| `到`              | 兩者之一          | 內部目標：一次 vue-router push，例如 `'/?tool=enhanceddnsleaktest'` 以開啟工具抽屜。不處理 UTM                                                                             |
| `requireSettled` | 否（預設 `true`)  | 在顯示前等待該區塊的 settled 訊號。將 `false` 設為立即顯示——例如在 `進階`，或者是本來就不應依賴測試結果的橫幅                                                                                    |
| `transition`     | 否（預設 `true`)  | 淡入滑動式出現／消失。將 `false` 設為可立即切換                                                                                                                          |
| `sweep`          | 否（預設 `false`) | 當橫幅進入視窗時會播放的邊框光掃效果（再次進入時會重播）。會遵循 `prefers-reduced-motion`                                                                                             |

必須且只能有一個 `url` / `到` 必須存在——兩者都存在或都不存在都會驗證失敗。

## 部署橫幅

插槽會透過建置時的 glob（`import.meta.glob` 對 `frontend/data/banners/*.js`）來發現其資料，因此這些檔案必須先放好 **when `pnpm build` 運行** ——它們會被編譯進 bundle，而不是在執行時讀取。因此部署步驟如下：

1. 把資料檔放進 `frontend/data/banners/` 的建置機器上（CI 步驟、Docker 建置階段，或手動）。
2. 執行 `pnpm test` — `tests/banners.test.js` 會驗證目前存在的所有檔案：每個檔案都必須是純資料且可由 Node 載入，必填欄位必須是非空字串，且以下兩者必須且只能有一個： `url` / `到` 已設定（`utm` 僅搭配 `url`），英文文案必須完整，選用旗標必須是布林值，而 id 必須唯一。若沒有任何檔案，這個檢查會自動通過。
3. 照常建置與部署。

移除橫幅則是反向操作：刪除該檔案（或將其設為 `export default null`）然後重新建置。無論哪種方式，git 裡都不會有變更。

## 分析

一次點擊會透過應用程式既有的分析包裝器送出一個事件：類別 `區塊`，事件名稱 `BannerClick_<section>`，標籤 = 該橫幅的 `track` 值。區塊會放在事件名稱中，而不是參數裡，因為 GA4 報表預設就會列出事件名稱。

## 下一節

* [前端](/developer/zh-tw/architecture/frontend.md) ——插槽在元件架構中的位置。
* [與 IPCheck.ing 綁定的功能](/developer/zh-tw/configuration/features-tied-to-ipcheck-ing.md) ——那些 *是* 僅限官方網站；橫幅不在其中。
* [測試](/developer/zh-tw/development/testing.md) ——驗證資料檔的測試執行器。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/zh-tw/configuration/section-banners.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.