O3noBLOG

08月 18日

Shopify App

之前開發 Shopify App 時，為了搞定他的安裝搞了蠻久，所以決定來紀錄一下踩到的坑，這篇文章適合已經開始在開發 Shopify App 的人閱讀，有些 Shopify App 的基本知識就不會提到，以下內文幾個名詞先定義清楚一下：

App 指的是我們開發的 Shopify 第三方 app
Merchant 指的是在 Shopify 上開店的商家
安裝 app 指的是 merchant 在他們的 Shopify 商店上安裝我們開發的第三方 app

首先就是，我踩的很多坑有一部分原因是因為我用 NodeJS 作為 server 端的語言，選的是 Express，但是官方的 Express 架構的 app 範例已經停止維護了，取而代之的，是 Koa 版本的 @shopify/koa-shopify-auth，只有負責驗證相關的 middleware，不過其實我也就剛好是需要 auth 相關的部分，只是差在不是 Express 版，我也還可以研究看看要怎樣自己實作了。

大概看一下，發現其實還有另外一個 @shopify/shopify-api 是底層負責處理跟 Shopify 相關的邏輯，所以理論上我也可以使用它來搭配 Express，不過這裡首先就有一個坑了，初始化的範例是長這樣：

Shopify.Context.initialize({
  API_KEY: process.env.SHOPIFY_API_KEY,
  API_SECRET_KEY: process.env.SHOPIFY_API_SECRET,
  SCOPES: process.env.SHOPIFY_APP_SCOPES,
  HOST_NAME: process.env.SHOPIFY_APP_URL.replace(/^https:\/\//, ''),
  API_VERSION: ApiVersion.October20,
  IS_EMBEDDED_APP: true,
  // More information at https://github.com/Shopify/shopify-node-api/blob/main/docs/issues.md#notes-on-session-handling
  SESSION_STORAGE: new Shopify.Session.MemorySessionStorage(),
});

可以看到，最後有一個SESSION_STORAGE，這是個處理 merchant 在安裝 app 時，我們的 app 拿到的 access token 的儲存方式的 adapter，不過官方的範例是用 Memory Storage，這個 adpater 是只有存在記憶體內，其實只適用於開發用，只要你的 server 一重開，所有的 merchant 就都要重新安裝你的 app，不然你的 app 會沒有 access token 跟 Shopify 溝通，實際上你應該要參考 Custom Session Storage 這份文件，挑選適用的 adapter，我則是參考範例寫了一個 GCP FireStore 的版本，當然另外沒特別提到的就是，因為是儲存 access token，最好要考慮一下 DB 的加密。

第二個坑，就是要怎樣做 Shopify 的 authentication 以及 identification，先來說如何驗證 request 是可信的，在 Shopify API 的設計，就是要靠 query string parameter 裡面的 hmac，他是根據你的 App 的 secret 來計算出來的，然後，這裡的坑就是官方套件@shopify/shopify-api內有個validateHmac可以用，但是它的計算其實是不正確的，它是用白名單只有取部分的 query string parameter 來計算，結果和 Shopify 給的就會有出入，所以我是參考 GitHub issue 討論串內 Muhammad Kamal 給的範例來使用。

第三個坑，則是安裝 App 用的 route 了，Shopify 的設計有點特別，所有的初始 request （不論是第一次安裝、還是從 Shopify 後台進入 App 的設定畫面），都長的很接近，所以你就要根據各種狀況來決定該做什麼事情，以下是所有可能的狀況：

第一次來安裝
安裝後進到設定畫面
曾經安裝過，但是需要重新授權，可能的原因：
- App 需要的權限有變動
- App 端的 access token 失效了
Shopify 認為已經安裝了，但是 app 端沒資料

扣除需要的權限有變動之外，其實就是排列組合，Shopify 端認為有沒有安裝過，和 App 端認為有沒有安裝過，二乘二共四種可能性，不過實際上只有三種處理方式：初次安裝、重新授權、安裝沒問題的快樂路線（happy path）整理成程式流程大概是：

驗證 hmac，沒過可以直接回 400
判斷 shop 是否有在資料庫中
2 有的話驗證資料庫中的 access token
3 驗證通過的話，狀態就是 happy path，Shopify 認為 app 有裝，app 端檢查也沒問題，我把這狀態命名為valid
3 驗證沒通過的話，判斷有沒有session這個 query string 參數
5 有的話，狀態就是 app 端的 access token 不能用了，需要走重新授權的流程，我把這狀態命名為invalid
5 沒有的話，就是第一次安裝的流程，我把這狀態命名為not_found
最後就是 2 沒有的話也是走初次安裝的授權流程，同樣也可以叫not_found

然後 app 需要的權限變動的話，理論上是每次進來，驗證 access token 的時候，可以去打 API 問目前 token 的 access scope，不過這部份我沒實做，因為目前我還沒有相關需求。

網路上可能可以找到X-Shopify-API-Request-Failure-Reauthorize這個 header，不過這個其實不是 Shopify API 的回應，而是 Shopify 的 app-template 裡面設計的機制，它們的 app template 裡面，server 端在轉發 Ajax API request 時，如果收到 Shopify 端的錯誤後，就加上這個 header 回給 app 前端，app 前端收到這個 header 後就可以透過 Shopify app-bridge 進入重新授權的流程。

講到這邊，或許有人會好奇，為什麼需要把安裝 app 和重新授權兩個流程的處理方式分開？其實這可以算是第四個坑，也是和使用者體驗有關係，狀況就是，Shopify 認為是初次安裝時，是直接進入 OAuth 的流程，所以是瀏覽器的最上層視窗直接轉址到 auth 頁面，但是如果是需要重新授權的情形，則是 Shopify 端認為已經安裝好，但是 app 這邊認為需要重新跑一次 OAuth，而這時候，連到 app server 的瀏覽器視窗是在 Shopify 商店後台的 iframe 內，在 iframe 內也無法正確的完成 OAuth 授權，所以需要用 Shopify 現在一套叫 app-bridge 的工具幫忙，讓 OAuth 流程從最上層視窗開始，所以需要回一個 HTML 頁面，引入 app-bridge 的 script，然後執行以下的的 JS：

const AppBridge = window['app-bridge'];
const createApp = AppBridge.default;
const Redirect = AppBridge.actions.Redirect;
const app = createApp({
	apiKey: '{{API_KEY}}',
	host: '{{HOST}}',
});
const redirect = Redirect.create(app);

redirect.dispatch(
	Redirect.Action.REMOTE,
	'/url/to/your/auth?shop={{SHOP}}'
);

當然記得要把該替換的東西替換上去，然後就可以看到正確的從最上層視窗開始進入 OAuth 授權的流程了。

最後一個坑，其實就是 merchant 反安裝 app 後，Shopify 和 app 端的狀態就會不一致的問題，Shopify 端認為沒安裝，但是 app 端認為有安裝，雖然我上面設計的程式流程已經可以處理這種狀況（驗證 access token 會失敗，然後沒有session參數，所以會進入初次安裝），但是這種情形還是應該要能避免就避免，而解法就是要支援 webhook，要作的事情就是：

安裝完成的 callback 去訂閱APP_UNINSTALLED這個 webhook event
然後在收到這個事件後，把資料庫中的對應資料刪除

這邊我是用@shopify/shopify-api提供的工具像是Shopify.Webhooks.Registry.register和Shopify.Utils.deleteOfflineSession，真的想要自己作也不是辦不到，不過我記得 Shopify 的 webhook 處理起來有點麻煩。

這些細節就是官方文件沒有好好寫清楚，雖然官方文件內容已經很多，有努力整理了，但是實際上要自己接就還是遇到了不少問題，所以特別寫一篇文章紀錄，雖然不知道會不會有其他中文圈的人需要自己來做 Shopify app 就是了，可以直接用他們的 app template 還是比較簡單啦。

單篇彙整