新增 APP

• 串接第 0 步：到 https://partner.cyberbiz.io/account/signUp 註冊開發者帳號，並在該開發者帳號建立 app ，建立的流程可參考此文件。

  • 建立好 APP 後，即可在 APP 設定頁中看到測試店，透過後台提供的連結可直接進到測試店後台進行測試

    

• 在 CYBERBIZ Partner 後台，partners 可以自行設定上架內容 (例如 App Icon、App 說明、… )，並可從後台取得 Client ID 與 Client Secret。

• App 需設定的資料

  | scopes | must | 空白分隔，預設為 public

  scope 列表參考 ‣ (預設只會先給 public 這個 scope) | | | --- | --- | --- | --- | | authorize_url | optional | 安裝流程第一步跳轉的 URL，讓 app 知道有誰來安裝，app自己紀錄最終安裝結果 資安考量，僅支援 https

  商家安裝 APP 時，瀏覽器會跳轉到這個頁面，為 GET request

  點擊開發者後台，該 APP 頁面的的「安裝測試」按鈕，即可開始測試整個安裝流程 | | | redirect_url | must | oauth redirect url，會帶 code 過去 資安考量，僅支援 https | | | webhook_url | optional | 事件列表 資安考量，僅支援 https

  Webhook 為 POST requests | |

APP 安裝流程

1. 驗證登入店家，此步驟會將下方資訊使用跳轉 (redirect) 方式導到 App 的 Authorization URL。

   hmac = OpenSSL::HMAC.hexdigest(
   	OpenSSL::Digest.new('sha256'),
   	your_oauth_application.secret,
   	Base64.strict_encode64(domain)
   )
   url = "app-authorization-url?shop=#{cyberbiz_domain}&hmac=#{hmac}"
   
   # EX: <https://partner-domain.com/?shop=demo.cyberbiz.co&hmac=47532a9c63a83037603d6b16d4a44e551c28e6e560804e179c6e2b62cf38f248>
   # GET <https://partner-domain.com/?shop=demo.cyberbiz.co&hmac=47532a9c63a83037603d6b16d4a44e551c28e6e560804e179c6e2b62cf38f248>
   

2. APP 從開發商驗證頁面跳轉回 CYBERBIZ https://{cyberbiz_domain}/admin/oauth/authorize (GET request)

   <aside> 🚨 務必實做 state 參數，避免遭受 CSRF 攻擊，造成資料外洩

   </aside>

   client_id	your oauth app client_id
   redirect_uri	your oauth app redirect_url
   response_type	code
   scope	(optional)
   your oauth app scopes split by whitespace. e.g: scope=public read_customers read_products ****
   state	random string to prevent CSRF

3. CYBERBIZ APP 授權安裝

   進到這畫面後，勾選並按下確認

   

4. 安裝完成跳轉至 App 的 Redirect URL (redirect_url)跳到 Redirect URL 時會帶的參數有

   code	oauth grant code (Valid within 10 minutes
   shop	shop.domain
   hmac	同第 1 點，可拿兩者做比對驗證（不用特別解開）
   state	state

到這步安裝流程就完成了，App 可以用取得的 code 跟 CYBEBIZ 要 token

通常這一步之後就是跳到 App 自己的設定畫面，或符合條件的話也可以進行 設定頁面自動帶入設定

取得 token

• 用 code 可以跟 EC 取得 access token 與 refresh token：
  • code 的有效期限為 10 分鐘。
  • code 為一次性有效。使用過一次後，就不能再用第二次。
  • access token 時效可以從 access token (JWT) 中的 exp 欄位知道何時過期，目前有效期限是 2 小時，但有可能更動。
  • access token 過期後，就會需要用 refresh token 重新要一個新的。
• 商家反安裝 APP 後，access token 與 refresh token 會同時失效。 需再走重新走一次安裝流程，拿到 grant code、再要到 refresh token、access token