跳至主要內容

自訂你的 UI

除了預設的 UI 客製化選項外，Logto 允許你自帶 UI，完全取代內建的登入體驗介面。這項功能讓你可以上傳包含自訂 UI 資產（HTML、CSS、JavaScript、圖片等）的 zip 檔，並將其託管於 Logto Cloud 伺服器，作為租戶使用者的 登入體驗。

備註:

此功能要求你的自訂 UI 必須相容於單頁應用程式（SPA, Single Page Application），並建議始終使用正式環境（production）的建置版本以獲得最佳效能。

在 Logto Console 體驗自訂 UI 功能​

使用官方專案快速開始​

最快啟動自訂登入 UI 的方式是複製 Logto experience 專案。這是 Logto 內建的登入體驗 UI，涵蓋所有功能並遵循 Logto 最佳實踐。你可以根據需求進行自訂。

檢出程式碼後，只需執行以下指令建置專案：

pnpm install && pnpm build
備註:

整個 Logto 專案是 pnpm monorepo。如果你想單獨執行 experience 套件（不使用 pnpm），請將 package.json 中的 workspace: 依賴項改為具體版本號（如 ^1.0.0）。

建置完成後，所有編譯後的資產都會在 dist 目錄下。然後將 dist 目錄壓縮成 ZIP 檔案——這個檔案稍後將用於上傳至 Logto Cloud。

自訂 UI 資產要求​

上傳自訂 UI 資產前，請確保符合以下要求：

  • 上傳資產需打包為單一 zip 檔。
  • zip 檔根目錄需包含 index.html 檔案。
  • zip 檔大小不得超過 20MB。
  • zip 檔內單一檔案不得超過 10MB。
  • zip 檔內檔案總數不得超過 200 個。

上傳你的自訂 UI 資產​

備註:

在正式環境使用此功能時請謹慎，因為它會立即影響使用者的登入體驗。

  1. 前往 Console > 登入與帳號 > 品牌設定 > 自訂你的 UI。
  2. 點擊選擇或拖曳你在前一步建立的 zip 檔，系統將自動開始上傳。
  3. 上傳完成後，儲存變更，你的自訂 UI 將立即生效。
  4. 當你使用自訂登入 UI 時，「登入預覽」視窗將會停用。不過，你仍可點擊「即時預覽」按鈕，在新開的瀏覽器分頁測試你的自訂登入頁面。

設定自訂 CSP 來源​

Logto 會為自訂 UI 頁面套用 Content Security Policy (CSP) header。如果你的自訂 UI 需要載入第三方腳本，或連線到外部服務，可以在 Console > 登入與帳號 > 品牌設定 > 自訂你的 UI 中新增額外允許的來源。

你可以設定：

  • script-src：允許 JavaScript module 或 script 的來源，例如 CAPTCHA、分析工具或 tag manager 服務。
  • connect-src：允許 fetch、XMLHttpRequest、EventSource 和 WebSocket 連線使用的網路端點。

範例：

{
  "scriptSrc": ["https://scripts.example.com"],
  "connectSrc": ["https://api.example.com", "wss://events.example.com"]
}

兩個 directive 都應使用 HTTPS origin。對於 WebSocket 連線，connect-src 也支援 wss:// origin。只有當自訂 UI 資產處於啟用狀態時，Logto 才會將這些來源追加到現有安全策略中。

開發你的自訂 UI​

與 Experience API 互動​

你的自訂 UI 需與 Experience API 互動，以執行登入、註冊、重設密碼、綁定社交帳號、啟用 MFA 等各種操作。為更好理解使用者流程與實作細節，建議參考我們的 Experience API 設計 RFC，其中提供完整技術規格與範例。

你也需要透過 sign-in Experience API endpoint 取得其他登入體驗設定，例如品牌色、公司 logo、favicon、密碼政策、本地化語言字串，甚至自訂 CSS。

啟用 CAPTCHA 時的處理方式​

Logto 內建登入體驗會自動處理 CAPTCHA。如果你的租戶啟用自訂 UI 並開啟 CAPTCHA 機器人防護，你的自訂 UI 必須在呼叫 PUT /api/experience 前完成前端 CAPTCHA 整合。

請將驗證服務提供者回傳的權杖作為 captchaToken，放入 PUT /api/experience 請求的 body。詳情請參閱各服務提供者的指引：

範例專案​

我們提供一系列範例專案，協助你快速理解並開始實作自訂 UI。詳情請參閱 Logto Experience project GitHub 儲存庫。

此外，我們將持續推出更多簡化且情境導向的範例專案，以涵蓋最常見的使用情境，敬請期待未來更新！

本地開發與除錯​

針對本地開發與除錯，我們提供 Logto Tunnel CLI 工具，可用於：

  • 將本機的 Experience API 請求代理至 Logto Cloud 端點。
  • 在本地測試你的自訂 UI 實作。

這讓你能在上傳至 Logto Cloud 前，於本地測試與除錯自訂 UI。

詳情請參閱 本地除錯與測試自訂 UI。

使用 CLI 上傳自訂 UI 資產​

除了透過 Console 上傳外，你也可以使用 Logto CLI 上傳自訂 UI 資產。這對於自動化部署流程特別有用。

詳情請參閱 使用 CLI 上傳自訂 UI 資產。

還原為 Logto 內建登入體驗​

若你希望還原為 Logto 內建的登入體驗，只需點擊自訂 UI 卡片上的刪除按鈕。儲存變更後，登入體驗 UI 將恢復為 Logto 預設樣式。

RFCS：Experience API

 Experience samples 將自訂登入 UI 帶到 Logto Cloud