疑難排解 — Shopify 順豐自取
設定 HK Pickup 時的常見問題，以及在安裝、佈景主題 App embed及管理設定後的結帳驗證檢查清單。
在 Shopify App Store 安裝 HK Pickup →
驗證結帳是否正常
Section titled “驗證結帳是否正常”在正式或預覽店面使用，上線前確認 HK Pickup 運作正常。
- App embed 已開啟且佈景主題已儲存
- 管理設定中至少啟用一種自取類型
- 香港自取點須可運送到香港；若開啟澳門一列，亦須可運送到澳門
開啟配送對話框
Section titled “開啟配送對話框”- 將任何商品加入購物車。
- 開啟購物車——購物車頁或購物車側欄。
- 按 Checkout（結帳）。
預期： 標題為 Choose delivery（選擇配送方式）（或你的自訂標題）的對話框，包含 SF Express pickup（順豐速運自取） 及 Ship to my address（送貨上門）。
若沒有出現，請見下方按結帳無對話框。
測試順豐速運自取
Section titled “測試順豐速運自取”- 按 SF Express pickup（順豐速運自取）。
- 若兩個地區都已啟用，先選香港或澳門，再用 Service type（服務類型）、**District（地區）**及 Search（搜尋） 尋找地點。
- 選取一列（應會高亮），然後 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（與店面語言一致） |
這些會在結帳重新導向之前寫入購物車，因此即使顧客修改預填送貨地址，仍會保留在訂單上。
若你已取消勾選 訂單屬性，訂單上不會有任何 _sf_* 屬性。上方的送貨地址預填仍然適用。
測試送貨上門
Section titled “測試送貨上門”- 返回購物車並再次按 Checkout（結帳）。
- 按 Ship to my address（送貨上門）。
預期： 對話框關閉，一般 Shopify 結帳開啟——無順豐自取地址預填。
訂單屬性（送貨上門）——Additional details（附加詳情） 應顯示 _sf_delivery_mode = home，且無 _sf_pickup_* 欄位。
購物車頁與購物車側欄
Section titled “購物車頁與購物車側欄”| 介面 | 如何測試 |
|---|---|
| 購物車頁 | 前往 /cart，按結帳 |
| 購物車側欄 | 從商品頁加入購物車，開啟側欄，按結帳 |
兩者應顯示相同的配送對話框。若其中一個失效，見購物車頁有對話框但側欄沒有。
語言（可選）
Section titled “語言（可選）”切換店面語言，再從購物車開啟結帳。對話框標籤及篩選應與目前語言一致。
快速檢查清單
Section titled “快速檢查清單”| 測試 | 通過 |
|---|---|
| 按結帳開啟對話框 | ☐ |
| 順豐自取 → 地點 → 預填結帳 | ☐ |
| 送貨上門 → 一般結帳 | ☐ |
| 購物車側欄結帳正常 | ☐ |
| 訂單屬性符合上方表格 | ☐ |
開發者模式： 串接 hkpickup.open() 後，執行相同的順豐自取及送貨上門檢查。事件測試見 開發者模式。
| 症狀 | 處理 |
|---|---|
| 開發者模式開啟，對話框從未開啟 | 你必須呼叫 window.hkpickup.open() 或串接結帳按鈕——見 開發者模式 |
| 開發者模式關閉，結帳無對話框 | 啟用 App embed；見按結帳無對話框 |
| 開發者模式開啟時結帳直接前往 Shopify | 預期行為——加入自訂 JS 開啟對話框 |
| 自取已儲存，但結帳送貨地址是空的 | 另一個應用程式擁有結帳按鈕，並開啟寫死的 /checkout。見 覆寫寫死的結帳網址 |
按結帳無對話框
Section titled “按結帳無對話框”| 檢查 | 處理 |
|---|---|
| App embed 關閉 | Online Store → Themes → Customize → App embeds → HK Pickup → on（開啟） → Save（儲存） |
| 未批准方案／試用未生效 | 開啟 Apps → HK Pickup——若被重新導向，請完成 Shopify 方案批准。或至 Settings → Apps 確認應用程式已安裝並計費 |
| 錯誤佈景主題 | 在已發佈佈景主題啟用 App embed，而非舊複本 |
| 快取頁面 | 強制重新整理店面或在無痕視窗測試 |
| 佈景主題選擇器 | 見佈景主題編輯器設定——若 auto 失敗請嘗試覆寫 |
檢查店面回應
Section titled “檢查店面回應”若忘記批准方案（或試用已結束），店面仍會回傳 HTTP 200——並非錯誤頁。
- 開啟購物車頁。
- 開啟瀏覽器 DevTools → Network（網路） → 重新載入。
- 找到
/apps/hkpickup/storefront-config請求。 - 查看 JSON：
"subscriptionActive": false→ 訂閱未生效，結帳如同 App embed 關閉。請開啟 Apps → HK Pickup 並批准方案。"subscriptionActive": true仍無對話框 → embed 或佈景主題問題，非帳單。
購物車頁有對話框但側欄沒有
Section titled “購物車頁有對話框但側欄沒有”- 啟用 App embed 後儲存佈景主題。
- 加入商品，開啟側欄，按結帳。
- 若仍失效，在 App embed 設定將 Cart drawer selector（購物車側欄選擇器） 設為
cart-drawer。
自取列表空白或「找不到自取點」
Section titled “自取列表空白或「找不到自取點」”| 檢查 | 處理 |
|---|---|
| 未啟用自取類型 | Apps → HK Pickup → Pickup types（自取類型）——至少啟用一種 |
| 篩選過窄 | 清除 Service type（服務類型） 及 District（地區），清除搜尋 |
| 新安裝 | 等待數分鐘後重試 |
訂單沒有 _sf_* 屬性
Section titled “訂單沒有 _sf_* 屬性”| 檢查 | 處理 |
|---|---|
| 已關閉訂單屬性 | Apps → HK Pickup → Order attributes（訂單屬性）——勾選 Save SF Express details on the order，儲存後重新載入店面 |
| 訂單在變更前下單 | 設定只影響新訂單 |
「無法載入自取點」
Section titled “「無法載入自取點」”- 檢查網絡連線並重試。
- 確認應用程式仍已安裝（Settings → Apps（應用程式））。
- 若錯誤持續，請電郵 tech@k2.digital，附上商店網域及截圖。
「送貨上門」無法繼續結帳
Section titled “「送貨上門」無法繼續結帳”- 在 App embed 設定嘗試 Cart form selector（購物車表單選擇器） →
form#cart。 - 先在購物車頁測試——若該頁正常但側欄失效，專注於側欄選擇器覆寫。
結帳顯示「Shipping not available（無法運送）」
Section titled “結帳顯示「Shipping not available（無法運送）」”這通常是商店設定問題，而非 HK Pickup：
- 香港或澳門市場及運送設定檔（須與所選地區一致）
- 商品供應及庫存地點
- 訂單路由規則
HK Pickup 預填順豐自取的送貨地址——它不會建立運費。請在 Shopify 管理後台修正運送設定，然後再測試。
對話框語言錯誤
Section titled “對話框語言錯誤”| 來源 | 修正 |
|---|---|
| 店面語言設定 | 顧客目前使用的店面語言 |
| 自訂關閉（預設） | 內建應用程式擴充功能語言檔；可選 Translate & Adapt |
| 自訂開啟 | Apps → HK Pickup → Settings → Translations（翻譯）（en／zh-TW／zh-CN） |
設定頁要求重新登入
Section titled “設定頁要求重新登入”前往 Shopify 管理後台 → Apps → HK Pickup 重新整理工作階段。已儲存的設定保留在 HK Pickup——重新登入不會重設它們。
完整設定見 試用模式。常見問題：
| 症狀 | 處理 |
|---|---|
| 試用模式開，測試者無對話框 | 以顧客身份登入（非僅管理後台）→ 重新載入購物車頁 → 結帳 |
| 試用模式開，所有人都看到對話框 | 全面上線時關閉試用模式；確認白名單已儲存在已發佈佈景主題 |
| 試用模式開，無人看到對話框 | 加入白名單電郵或在 theme.liquid 設定 window.HKPICKUP_PILOT_ALLOW |
| 名單有電郵但不匹配 | 檢查拼寫（不區分大小寫）；顧客帳戶電郵必須完全一致 |
| 測試者仍看到舊應用程式 | 可能屬預期——一般訪客不受影響；可短暫停用舊 App embed 供測試者使用 |
| 在草稿佈景主題更改試用模式 | 發佈正式佈景主題——草稿設定不影響店面 |
驗證試用模式行為
Section titled “驗證試用模式行為”當 試用模式 開啟時（從其他應用程式遷移）：
| 對象 | 步驟 | 預期 |
|---|---|---|
| 訪客 | 加入購物車 → 結帳 | 無 HK Pickup 對話框——一般／舊應用程式結帳 |
| 白名單測試者 | 以顧客登入 → 重新載入購物車 → 結帳 | 配送對話框開啟——執行上方順豐自取及送貨上門檢查 |
| 標籤測試者 | 空白白名單 + theme.liquid 中的 HKPICKUP_PILOT_ALLOW + 顧客標籤 → 重新載入購物車 → 結帳 |
與白名單測試者相同——見試用模式 → 佈景主題標記 |
| 上線後 | 關閉試用模式 → 訪客結帳 | 所有人看到對話框；頁面設定中無測試者電郵 |
電郵 tech@k2.digital，附上：
- 你的
.myshopify.com網域 - 佈景主題名稱（顯示於 App embed 設定）
- 預期結果 vs 實際情況
- 截圖或短片（如可能）