疑難排解 — Shopify 順豐自取

設定 HK Pickup 時的常見問題，以及在安裝、佈景主題 App embed及管理設定後的結帳驗證檢查清單。

在 Shopify App Store 安裝 HK Pickup →

---

驗證結帳是否正常

在正式或預覽店面使用，上線前確認 HK Pickup 運作正常。

測試前

• App embed 已開啟且佈景主題已儲存
• 管理設定中至少啟用一種自取類型
• 商店銷售至香港且測試訂單的運送設定正常

開啟配送對話框

1. 將任何商品加入購物車。
2. 開啟購物車——購物車頁或購物車側欄。
3. 按 Checkout（結帳）。

預期： 標題為 Choose delivery（選擇配送方式）（或你的自訂標題）的對話框，包含 SF Express pickup（順豐速運自取） 及 Ship to my address（送貨上門）。

若沒有出現，請見下方按結帳無對話框。

測試順豐速運自取

1. 按 SF Express pickup（順豐速運自取）。
2. 使用 Service type（服務類型）、**District（地區）**及 Search（搜尋） 尋找地點。
3. 選取一列（應會高亮），然後 Continue to checkout（繼續結帳）。

預期： Shopify 結帳頁開啟，Shipping address（送貨地址） 已預填自取點。顧客仍需輸入姓名、聯絡方式及付款。

訂單屬性（順豐自取）——Shopify 管理後台 → Orders → Additional details（附加詳情）：

屬性	預期值
_sf_delivery_mode	pickup
_sf_pickup_code	你所選地點的順豐編號（例如 H852K067P）
_sf_pickup_type	SF Station、SF Locker 或 SF Partner Point
_sf_pickup_address	完整自取地址
_sf_pickup_region	所選網點的區域
_sf_pickup_district	所選網點的地區
_sf_pickup_locale	zh-HK、zh-CN 或 en-US（與店面語言一致）

這些會在結帳重新導向之前寫入購物車，因此即使顧客修改預填送貨地址，仍會保留在訂單上。

測試送貨上門

1. 返回購物車並再次按 Checkout（結帳）。
2. 按 Ship to my address（送貨上門）。

預期： 對話框關閉，一般 Shopify 結帳開啟——無順豐自取地址預填。

訂單屬性（送貨上門）——Additional details（附加詳情） 應顯示 _sf_delivery_mode = home，且無 _sf_pickup_* 欄位。

購物車頁與購物車側欄

介面	如何測試
購物車頁	前往 /cart，按結帳
購物車側欄	從商品頁加入購物車，開啟側欄，按結帳

兩者應顯示相同的配送對話框。若其中一個失效，見購物車頁有對話框但側欄沒有。

語言（可選）

切換店面語言，再從購物車開啟結帳。對話框標籤及篩選應與目前語言一致。

快速檢查清單

測試	通過
按結帳開啟對話框	☐
順豐自取 → 地點 → 預填結帳	☐
送貨上門 → 一般結帳	☐
購物車側欄結帳正常	☐
訂單屬性符合上方表格	☐

開發者模式： 串接 hkpickup.open() 後，執行相同的順豐自取及送貨上門檢查。事件測試見 開發者模式。

---

開發者模式

症狀	處理
開發者模式開啟，對話框從未開啟	你必須呼叫 window.hkpickup.open() 或串接結帳按鈕——見 開發者模式
開發者模式關閉，結帳無對話框	啟用 App embed；見按結帳無對話框
開發者模式開啟時結帳直接前往 Shopify	預期行為——加入自訂 JS 開啟對話框

---

按結帳無對話框

檢查	處理
App embed 關閉	Online Store → Themes → Customize → App embeds → HK Pickup → on（開啟） → Save（儲存）
未批准方案／試用未生效	開啟 Apps → HK Pickup——若被重新導向，請完成 Shopify 方案批准。或至 Settings → Apps 確認應用程式已安裝並計費
錯誤佈景主題	在已發佈佈景主題啟用 App embed，而非舊複本
快取頁面	強制重新整理店面或在無痕視窗測試
佈景主題選擇器	見佈景主題編輯器設定——若 auto 失敗請嘗試覆寫

檢查店面回應

若忘記批准方案（或試用已結束），店面仍會回傳 HTTP 200——並非錯誤頁。

1. 開啟購物車頁。
2. 開啟瀏覽器 DevTools → Network（網路） → 重新載入。
3. 找到 /apps/hkpickup/storefront-config 請求。
4. 查看 JSON：
   • "subscriptionActive": false → 訂閱未生效，結帳如同 App embed 關閉。請開啟 Apps → HK Pickup 並批准方案。
   • "subscriptionActive": true 仍無對話框 → embed 或佈景主題問題，非帳單。

---

購物車頁有對話框但側欄沒有

1. 啟用 App embed 後儲存佈景主題。
2. 加入商品，開啟側欄，按結帳。
3. 若仍失效，在 App embed 設定將 Cart drawer selector（購物車側欄選擇器） 設為 cart-drawer。

---

自取列表空白或「找不到自取點」

檢查	處理
未啟用自取類型	Apps → HK Pickup → Pickup types（自取類型）——至少啟用一種
篩選過窄	清除 Service type（服務類型） 及 District（地區），清除搜尋
新安裝	等待數分鐘後重試

---

「無法載入自取點」

• 檢查網絡連線並重試。
• 確認應用程式仍已安裝（Settings → Apps（應用程式））。
• 若錯誤持續，請電郵 tech@k2.digital，附上商店網域及截圖。

---

「送貨上門」無法繼續結帳

1. 在 App embed 設定嘗試 Cart form selector（購物車表單選擇器） → form#cart。
2. 先在購物車頁測試——若該頁正常但側欄失效，專注於側欄選擇器覆寫。

---

結帳顯示「Shipping not available（無法運送）」

這通常是商店設定問題，而非 HK Pickup：

• 香港市場及運送設定檔
• 商品供應及庫存地點
• 訂單路由規則

HK Pickup 預填順豐自取的送貨地址——它不會建立運費。請在 Shopify 管理後台修正運送設定，然後再測試。

---

對話框語言錯誤

來源	修正
店面語言設定	顧客目前使用的店面語言
自訂關閉（預設）	內建應用程式擴充功能語言檔；可選 Translate & Adapt
自訂開啟	Apps → HK Pickup → Settings → Translations（翻譯）（en／zh-TW／zh-CN）

---

設定頁要求重新登入

前往 Shopify 管理後台 → Apps → HK Pickup 重新整理工作階段。已儲存的設定保留在 HK Pickup——重新登入不會重設它們。

---

試用模式

完整設定見 試用模式。常見問題：

症狀	處理
試用模式開，測試者無對話框	以顧客身份登入（非僅管理後台）→ 重新載入購物車頁 → 結帳
試用模式開，所有人都看到對話框	全面上線時關閉試用模式；確認白名單已儲存在已發佈佈景主題
試用模式開，無人看到對話框	加入白名單電郵或在 theme.liquid 設定 window.HKPICKUP_PILOT_ALLOW
名單有電郵但不匹配	檢查拼寫（不區分大小寫）；顧客帳戶電郵必須完全一致
測試者仍看到舊應用程式	可能屬預期——一般訪客不受影響；可短暫停用舊 App embed 供測試者使用
在草稿佈景主題更改試用模式	發佈正式佈景主題——草稿設定不影響店面

驗證試用模式行為

當 試用模式 開啟時（從其他應用程式遷移）：

對象	步驟	預期
訪客	加入購物車 → 結帳	無 HK Pickup 對話框——一般／舊應用程式結帳
白名單測試者	以顧客登入 → 重新載入購物車 → 結帳	配送對話框開啟——執行上方順豐自取及送貨上門檢查
標籤測試者	空白白名單 + theme.liquid 中的 HKPICKUP_PILOT_ALLOW + 顧客標籤 → 重新載入購物車 → 結帳	與白名單測試者相同——見試用模式 → 佈景主題標記
上線後	關閉試用模式 → 訪客結帳	所有人看到對話框；頁面設定中無測試者電郵

---

聯絡支援

電郵 tech@k2.digital，附上：

• 你的 .myshopify.com 網域
• 佈景主題名稱（顯示於 App embed 設定）
• 預期結果 vs 實際情況
• 截圖或短片（如可能）