網站嵌入技術指南

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

快速開始

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

懶人包

引入腳本：在 HTML <body> 結束前加入一段 <script>

設定 ID：設定 window.roomDreamingConfig 中的 agentId

觸發方式：選擇浮動按鈕、自定義按鈕或產品綁定

技術原理

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

基本嵌入

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

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

    // 選用：是否開啟右下角預設的浮動按鈕 (預設 false)
    floatingWidget: {
      enabled: true,
      tooltipText: "打造自己的家", // 提示文字
      buttonText: "立即體驗", // 按鈕文字
    },
  };
</script>

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

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

進階觸發設定

如果您希望使用者點擊網站上原本的按鈕（例如 Navbar 或產品卡片）來喚起展間，請參考以下做法。

我們支援 MutationObserver，因此即使是 SPA 動態生成的內容也能運作。

情境 A：純粹開啟展間

適用於首頁 Banner 按鈕或選單按鈕，不指定特定產品。

<button data-rd-custom-button="true">開啟 AI 展間</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。

Data Attributes 參考

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

設定參數參考

interface RoomDreamingConfig {
  // 必填：商戶 ID
  agentId: string;

  // 選用：浮動按鈕設定
  floatingWidget?: {
    enabled: boolean; // 是否啟用
    tooltipText?: string; // hover 提示文字
    buttonText?: string; // 按鈕文字
  };
}

常見技術問答

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

Z-Index 層級是多少？

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

是否支援 SPA？

是的。Loader 會自動監聽 DOM 變化，即使頁面無刷新切換，新生成的按鈕只要帶有對應的 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",
        floatingWidget: { enabled: true }
      };
    `,
  }}
/>
<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 的錯誤訊息截圖
使用的前端框架與版本