網站嵌入技術指南

本頁面是給官網技術團隊參考的整合文件。如果您是建材廠商內部團隊，請參考網站嵌入模式的設定說明。

快速開始

目標：在現有官網（建材廠商）中，以最不影響原網站架構的方式，加入「RoomDreaming AI 智慧選材系統」。

嵌入腳本：在 HTML <body> 結束前加入 <script> 設定 agentId

選擇觸發方式：根據需求在 HTML 加入對應的 data attribute 或 URL 參數

技術原理

項目	說明
運作方式	透過 JavaScript Loader 動態載入一個覆蓋全螢幕的 `iframe` (Modal 形式)
隔離性	主程式運行於 iframe 內，樣式與邏輯完全隔離，不會污染母體網站
效能	Loader 腳本極輕量且採 `async` 非同步載入，不阻塞渲染流程
相容性	原生 Vanilla JS，相容任何框架 (React, Vue, WordPress, PHP 等) 及 RWD

Step 1：嵌入腳本

請將以下程式碼放置於全站 Layout 的 </body> 結束標籤之前：

<!-- RoomDreaming Configuration -->
<script>
  window.roomDreamingConfig = {
    // 必填：我們會提供給您專屬 AGENT_ID
    agentId: "YOUR_AGENT_ID_HERE",
  };
</script>

<!-- RoomDreaming Loader (Async) -->
<script async src="https://app.roomdreaming.com/loader.js"></script>

agentId 可在系統後台的「整合設定」頁面取得。

Step 2：選擇觸發方式

RoomDreaming 提供多種方式讓使用者開啟選材系統：

方式	觸發時機	適用場景	需要頁面跳轉	設定方式
浮動按鈕	點擊右下角浮動按鈕	全站通用入口	否	系統後台設定
自定義按鈕	點擊帶有 `data-rd-custom-button` 屬性的元素	Navbar、Banner、CTA 按鈕	否	HTML 加入屬性
產品按鈕	點擊帶有 `data-rd-product-id` 屬性的元素	產品列表、產品詳情頁	否	HTML 加入屬性
URL 參數	頁面載入時檢測 `open_rd=true` 參數自動開啟	EDM、社群連結、QR Code 外部導流	是	連結加入參數

浮動按鈕由廠商在 RoomDreaming 後台設定，無需在 HTML 中額外處理。以下將詳細說明需要在 HTML 中實作的三種觸發方式。

觸發方式詳細說明

方式 A：自定義按鈕

讓網站上原本的按鈕（例如 Navbar 或 Banner）來喚起選材系統，不指定特定產品。

只需在任何 HTML 元素加上 data-rd-custom-button 屬性：

<button data-rd-custom-button>開啟 AI 選材</button>

支援任何 HTML 元素：data-rd-custom-button 不限於 <button>，可用於 <a>、<div>、<span>、<img> 等任何可點擊的元素。

<!-- 以下寫法皆有效 -->
<button data-rd-custom-button>按鈕</button>
<a data-rd-custom-button>連結</a>
<div data-rd-custom-button>區塊</div>
<img src="banner.jpg" data-rd-custom-button />

方式 B：產品按鈕

適用於「產品列表」或「產品詳情頁」，點擊後直接在選材系統中預覽該材質。

<!-- 只指定產品 ID -->
<button data-rd-product-id="prod_123">試鋪此地板</button>

<!-- 同時指定產品 ID 與變體 ID -->
<button data-rd-product-id="prod_123" data-rd-variant-id="var_456">
  試鋪此顏色
</button>

<!-- 只指定變體 ID（系統會自動找到對應產品） -->
<button data-rd-variant-id="var_456">試鋪此款式</button>

prod_123 和 var_456 需替換為您在 RoomDreaming 系統中建立的實際產品/變體 ID。可在後台「商品管理」頁面查詢。

產品按鈕同樣支援任何 HTML 元素，不限於 <button>。

方式 C：URL 參數觸發

適用於從外部連結（如 EDM、社群貼文、QR Code）導流進入網站時，自動開啟選材系統。

https://your-website.com/products?open_rd=true
https://your-website.com/products?open_rd=true&selected_product=prod_123
https://your-website.com/products?open_rd=true&selected_variant=var_456

當使用者透過帶有 open_rd=true 參數的連結進入頁面時，選材系統會在頁面載入後自動開啟。

URL 參數 vs Data Attribute 的差異： - data-rd-custom-button：點擊後立即開啟，無頁面跳轉 - open_rd=true：頁面載入後自動開啟，適合外部導流

參考資料

Data Attributes

Attribute	說明	範例值
`data-rd-custom-button`	標記為自定義觸發按鈕	`"true"`
`data-rd-product-id`	指定要帶入的產品 ID	`"prod_123"`
`data-rd-variant-id`	指定要帶入的變體 ID（選填）	`"var_456"`

URL 參數

參數	說明	範例值
`open_rd`	設為 `true` 時自動開啟	`"true"`
`selected_product`	開啟時預選的產品 ID	`"prod_123"`
`selected_variant`	開啟時預選的變體 ID	`"var_456"`
`rd_source`	流量來源追蹤（選填）	`"edm_2024"`

常見技術問答

不會。內容透過 iframe 載入，且腳本非同步執行，不影響爬蟲抓取主要網站內容。

Z-Index 層級是多少？

預設層級為 9999，確保蓋在大多數網頁元素之上。如果您的網站有更高的 z-index 元素，請聯繫我們調整。

是否支援 SPA？

是的。Loader 會自動監聽 DOM 變化（使用 MutationObserver），即使頁面無刷新切換，新生成的按鈕只要帶有對應的 data 屬性依然有效。

如何在 React/Vue 中使用？

由於是原生 JavaScript，可以直接在任何框架中使用：

React (Next.js)

// pages/_document.tsx 或 app/layout.tsx
<Script
  id="roomdreaming-config"
  strategy="beforeInteractive"
  dangerouslySetInnerHTML={{
    __html: `
      window.roomDreamingConfig = {
        agentId: "YOUR_AGENT_ID_HERE"
      };
    `,
  }}
/>
<Script
  src="https://app.roomdreaming.com/loader.js"
  strategy="afterInteractive"
/>

Vue (Nuxt)

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          children: `window.roomDreamingConfig = { agentId: "YOUR_AGENT_ID_HERE" };`,
        },
        { src: "https://app.roomdreaming.com/loader.js", async: true },
      ],
    },
  },
});

需要協助？

如果遇到技術問題，請聯繫 RoomDreaming 技術支援（email: contact@roomdreaming.com），並提供：

您的網站網址
瀏覽器 Console 的錯誤訊息截圖
使用的前端框架與版本