開發者模式 — Shopify 結帳整合 API

當其他應用程式或自訂結帳腳本與 HK Pickup 自動攔截結帳衝突，或你需要完全控制何時開啟配送對話框及如何繼續結帳時，請使用 開發者模式。

在 Shopify App Store 安裝 HK Pickup →

---

何時啟用

情況	開發者模式
單一 HK Pickup 安裝，預設結帳	關（建議）
其他應用程式攔截結帳	開——自行串接 hkpickup.open()
自訂結帳／無頭流程	開——監聽 hkpickup:* 事件

開發者模式 開啟時，HK Pickup 不會綁定結帳按鈕。除非你加入自訂 JavaScript，否則按結帳會直接前往 Shopify。

需要以自訂 JavaScript 控制「誰會看到對話框」？請用 開發者模式。從其他自取應用程式遷移時的一般正式結帳，請改用 試用模式——無需自訂程式碼。

---

在佈景主題編輯器啟用

1. Online Store → Themes → Customize（網上商店 → 佈景主題 → 自訂）
2. App embeds → HK Pickup
3. 開啟 Developer mode（開發者模式）
4. Save（儲存）

---

HK Pickup 仍負責什麼

職責	負責方
顯示配送對話框 UI	HK Pickup（當你呼叫 open() 時）
寫入購物車屬性（_sf_delivery_mode、_sf_pickup_*）	HK Pickup——在 home／confirm 事件之前
前往結帳／提交購物車表單	你（整合者）

若 /cart/update.js 失敗，HK Pickup 會在對話框顯示錯誤，且不會觸發 home 或 confirm 事件。

---

命令式 API（window.hkpickup）

只在開發者模式開啟時可用。

成員	說明
isReady	初始化及店面設定載入後為 true
open()	重設至第 1 步、顯示對話框、觸發 hkpickup:open
close(options?)	{ force?: boolean }——關閉對話框；觸發不可取消的 hkpickup:close，reason: 'api'。若先前阻止了 home/confirm 關閉，非同步工作完成後使用 force: true

---

事件

所有事件均為 document 的 CustomEvents，前綴為 hkpickup:。

在 hkpickup:ready 之後註冊監聽器（或檢查 window.hkpickup?.isReady）。

事件參考

事件	時機	detail
hkpickup:ready	初始化完成	{ developerMode: true, locale }
hkpickup:open	透過 open() 開啟對話框	{ source: 'api' }
hkpickup:close	對話框關閉前（開發者模式）	{ reason }——見下方可取消規則
hkpickup:home	選擇送貨上門（屬性已清除）	{ cartAttributes }
hkpickup:back	從順豐列表返回 → 第 1 步	{}
hkpickup:location-select	選中順豐列	{ store }
hkpickup:confirm	順豐確認（屬性已儲存）	{ store, checkoutUrl, cartAttributes }

不會觸發： 第 1 步「順豐速運自取」（僅內部）、篩選／搜尋變更。

store 物件

{
  "code": "H852K067P",
  "type": "store",
  "category": "store",
  "name": "SF Station …",
  "address": "…",
  "region": "Hong Kong Island",
  "city": "Central",
  "district": "Central"
}

cartAttributes 鍵

鍵	送貨上門	自取
_sf_delivery_mode	home	pickup
_sf_pickup_code	""	順豐編號
_sf_pickup_type	""	服務類型
_sf_pickup_address	""	地址
_sf_pickup_region	""	區域
_sf_pickup_district	""	地區
_sf_pickup_locale	""	zh-HK / zh-CN / en-US

---

可取消關閉（hkpickup:close）

只有 home 及 confirm 關閉原因可取消。監聽器可同步呼叫 event.preventDefault() 以保持對話框開啟（例如另一個外掛正在執行時）。

detail.reason	可取消？	行為
home	是	在 hkpickup:home 之後
confirm	是	在 hkpickup:confirm 之後
dismiss	否	X 按鈕或背景——一律關閉
api	否	hkpickup.close()——一律關閉

非同步模式：

document.addEventListener('hkpickup:close', (e) => {
  if (e.detail.reason !== 'confirm') return
  e.preventDefault()
  runOtherPlugin().finally(() => window.hkpickup.close({ force: true }))
})

事件順序（home／confirm）： 購物車屬性儲存 → hkpickup:home 或 hkpickup:confirm → 可取消的 hkpickup:close → 除非被阻止否則關閉。

---

Dawn 範例——自行攔截結帳

加入佈景主題自訂 JavaScript（或你的應用程式資源）：

document.addEventListener('hkpickup:ready', () => {
  document.querySelectorAll('button[name="checkout"]').forEach((btn) => {
    btn.addEventListener('click', (e) => {
      e.preventDefault()
      window.hkpickup.open()
    })
  })
})

document.addEventListener('hkpickup:home', () => {
  window.location.href = '/checkout'
})

document.addEventListener('hkpickup:confirm', (e) => {
  window.location.href = e.detail.checkoutUrl
})

若結帳按鈕不同，請為你的佈景主題調整選擇器。

---

除錯——記錄所有事件

貼到 DevTools 主控台，然後重新載入：

;['ready','open','close','home','back','location-select','confirm'].forEach((n) =>
  document.addEventListener(`hkpickup:${n}`, (e) =>
    console.log(`hkpickup:${n}`, e.detail, e.cancelable ? '(cancelable)' : '')
  )
)

---

測試

串接結帳後，在 驗證結帳 執行相同檢查。

---

相關

• 佈景主題編輯器設定——開發者模式核取方塊
• 疑難排解——開發者模式 FAQ