嵌入預約工具｜Reservalue 開發文件

簡介

widget 以 UMD bundle 發佈，載入後會在全域註冊一個 ReservalueWidget 類別。您只要引入一支 CSS、一支 JS，並在頁面放一個容器元素，再呼叫建構子即可。 widget 會自動載入它所需的相依套件，您不需要額外引入。

您也可以從後台的「服務 → 嵌入工具」使用視覺化編輯器調整樣式並自動產生嵌入碼，複製貼上後即可完成整合。

快速開始

三個步驟即可上線：

<!-- 1. 在 <head> 引入樣式與程式 -->
<link rel="stylesheet" href="https://static.reservalue.net/widget/v1/reservalue-widget.css">
<script src="https://static.reservalue.net/widget/v1/reservalue-widget.min.js"></script>

<!-- 2. 在頁面放一個容器 -->
<div id="reservalue-widget"></div>

<!-- 3. 初始化 -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    new ReservalueWidget('your-bu-link', 'your-service-link', {
      container: '#reservalue-widget',
      lang: 'zh-TW'
    });
  });
</script>

將 your-bu-link 換成您的事業連結、your-service-link 換成服務連結，這兩個值均可在後台取得。

需要引入的資源

正式環境只需引入以下兩個檔案（皆為穩定的 v1 路徑）：

資源	URL
樣式 (CSS)	`https://static.reservalue.net/widget/v1/reservalue-widget.css`
程式 (JS)	`https://static.reservalue.net/widget/v1/reservalue-widget.min.js`

Moment.js（含時區）、intl-tel-input 等相依套件由 widget 在初始化時自動載入，您不需要手動引入。

建構子

new ReservalueWidget(buLink, serviceLink, options)

buLink — 必填字串，事業連結。
serviceLink — 必填字串，服務連結。
options — 設定物件，欄位見下方。

設定參數

options 物件支援以下欄位：

參數	型別	必填	說明
`container`	string	必填	widget 掛載位置的 CSS 選擇器，例如 `'#reservalue-widget'`。
`lang`	string	選填	介面語系，預設 `'zh-TW'`。支援 `zh-TW` / `en` / `ja` / `ko`。
`styles`	object	選填	自訂顏色與外觀，結構見「自訂樣式」。
`showResultScreen`	boolean	選填	是否在送出後顯示結果畫面，預設 `true`。設為 `false` 可改用事件回呼自行處理。
`customField`	string	選填	自訂文字，於初始化時帶入，會隨此次預約一併送出並顯示在後台的預約詳情，適合夾帶活動代碼、推薦來源等自有追蹤資訊。最長 255 字元。

自訂樣式

透過 styles 物件可調整各區塊的顏色，讓 widget 融入您的品牌。所有欄位皆為選填，未填者沿用預設值。

styles: {
  header: { backgroundColor, color, borderBottomColor },
  content: { backgroundColor, color },
  footer: { backgroundColor, borderTopColor },
  button: {
    primary: { backgroundColor, color, borderColor, hoverEffect },
    secondary: { backgroundColor, color, borderColor, hoverEffect },
    slot: { backgroundColor, color, borderColor, hoverEffect }
  },
  result: { icon: { borderColor } },
  calendar: {
    backgroundColor, color, availableColor, disabledColor,
    today: { backgroundColor },
    selected: { backgroundColor }
  }
}

每個顏色值都是一般的 CSS 顏色字串，例如 '#e4007f' 或 'rgb(228,0,127)'。

三種按鈕

button 底下的 primary、secondary、slot 為三種可獨立設定的按鈕，每種都能各自指定 backgroundColor（背景）、color（文字）、borderColor（邊框）與 hoverEffect（滑鼠移上去的效果）。

按鈕	出現位置
`primary`　主按鈕	「下一步」、「送出」以及結果頁的操作按鈕。
`secondary`　副按鈕	「上一步」按鈕。
`slot`　時段按鈕	日曆中可預約的時段選擇按鈕。

`hoverEffect`：滑鼠移上去的效果

每個按鈕可獨立設定，未填時預設為 darken：

值	效果
`darken`	加深底色與邊框（預設）。
`invert`	背景色與文字色對調，類似外框按鈕被填滿的效果。
`lift`	按鈕微微浮起並加上柔和陰影。
`shadow`	加上陰影、不位移。
`grow`	整體略為放大。
`none`	無變化。

多語系

用 lang 參數切換介面語言，目前支援：

zh-TW — 繁體中文（預設）
en — English
ja — 日本語
ko — 한국어

填入不支援的語系時，會自動退回 zh-TW。

事件回呼

widget 實例提供下列事件註冊方法，方便您整合分析或自訂後續流程：

方法	觸發時機
`onReady(cb)`	widget 初始化完成、可開始操作時。
`onStepChange(cb)`	切換步驟時，回傳目前的步驟編號。
`onReservationRequestSubmitted(cb)`	使用者送出預約表單時。
`onReservationCreated(cb)`	預約建立成功，回傳 `{ reservationId }`。
`onReservationFailed(cb)`	預約建立失敗，回傳 `{ reason }`。
`onError(cb)`	發生任何錯誤時。

const widget = new ReservalueWidget('your-bu-link', 'your-service-link', {
  container: '#reservalue-widget'
});

widget.onReady(() => console.log('widget ready'));
widget.onReservationCreated((data) => console.log('預約成功', data.reservationId));
widget.onReservationFailed((data) => console.log('預約失敗', data.reason));

完整範例

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://static.reservalue.net/widget/v1/reservalue-widget.css">
  <script src="https://static.reservalue.net/widget/v1/reservalue-widget.min.js"></script>
</head>
<body>
  <div id="reservalue-widget"></div>

  <script>
    document.addEventListener('DOMContentLoaded', function () {
      const widget = new ReservalueWidget('your-bu-link', 'your-service-link', {
        container: '#reservalue-widget',
        lang: 'zh-TW',
        showResultScreen: true,
        styles: {
          header: { backgroundColor: '#000000', color: '#ffffff' },
          button: {
            primary: { backgroundColor: '#e4007f', color: '#ffffff', borderColor: '#e4007f' },
            slot: { backgroundColor: '#ffffff', color: '#e4007f', borderColor: '#e4007f', hoverEffect: 'invert' }
          }
        }
      });

      widget.onReservationCreated((data) => {
        console.log('Reservation created:', data.reservationId);
      });
    });
  </script>
</body>
</html>

需要協助整合？歡迎透過 LINE 或 support@reservalue.net 與我們聯繫。

嵌入預約工具

簡介