Clerk Android (原生)
此技能透過遵循現行 clerk-android SDK 與文件模式,在原生 Android 專案中實作 Clerk。
啟用規則
當以下任一條件成立時,啟用此技能:
- 使用者明確要求 Android、Kotlin、Jetpack Compose 或 Android 上的原生行動 Clerk 實作。
- 專案看起來是原生 Android(例如含有 Android 插件的
build.gradle(.kts)、AndroidManifest.xml、app/src/main/java、Compose UI 檔案)。
當以下任一條件成立時,不啟用此技能:
- 專案是 Expo。
- 專案是 React Native。
若出現 Expo/React Native 的訊號,請改用通用設定技能。
你需要什麼?
| 任務 | 參考文件 |
|---|---|
| 預建 AuthView / UserButton(最快) | references/prebuilt.md |
| 自訂 API 驅動認證流程(完整控制) | references/custom.md |
快速開始
| 步驟 | 動作 |
|---|---|
| 1 | 確認專案類型是原生 Android,而非 Expo/React Native |
| 2 | 決定流程類型(prebuilt 或 custom),並載入對應的參考檔案 |
| 3 | 確保存在真實的 Clerk publishable key(或詢問開發者) |
| 4 | 確保為所選流程安裝正確的 Clerk 構件 |
| 5 | 閱讀官方 Android quickstart,並驗證必要設定(Native API、最低 SDK/Java、manifest、初始化) |
| 6 | 檢查 clerk-android 原始碼/範例中與所選流程相關的模式 |
| 7 | 嚴格遵循選定的參考檢查清單來實作流程 |
決策樹
使用者要求在 Android/Kotlin 中使用 Clerk
|
+-- 偵測到 Expo/React Native 專案?
| |
| +-- 是 -> 不使用此技能
| |
| +-- 否 -> 繼續
|
+-- 偵測到現有認證 UI?
| |
| +-- 偵測到預建檢視 -> 載入 references/prebuilt.md
| |
| +-- 偵測到自訂流程 -> 載入 references/custom.md
| |
| +-- 全新實作 -> 詢問開發者預建/自訂,然後載入對應參考
|
+-- 確保 publishable key 與 SDK 初始化路徑
|
+-- 確保已安裝正確的 Android 構件
|
+-- 驗證專案中的 quickstart 前提條件
|
+-- 使用所選流程參考進行實作
流程參考
確認流程類型後,僅載入一個:
- 預建流程:references/prebuilt.md
- 自訂流程:references/custom.md
除非開發者明確要求混合方式,否則請勿在單一實作中混用兩個參考。
互動合約
在進行任何實作編輯之前,代理必須同時擁有:
- 流程選擇:
prebuilt或custom - 一個真實的 Clerk publishable key
若使用者請求/上下文中缺少任一值:
- 詢問使用者缺少的值
- 暫停並等待回答
- 在此之前,不要編輯檔案或安裝依賴
僅當使用者已在本次對話中明確提供該值時,才能跳過詢問。
源碼驅動的範本
請勿在此技能中硬編碼實作範例。在實作前,請檢查目前安裝的 SDK 版本對應的 clerk-android 原始碼/文件。
| 使用案例 | 真實來源 |
|---|---|
SDK 構件與依賴拆分(clerk-android-api 對比 clerk-android-ui) | clerk-android README 與 Android 安裝文件 |
| SDK 初始化與 publishable key 接線 | Android quickstart 與 source/api/.../Clerk.kt |
| 預建認證與個人資料行為 | source/ui/.../AuthView.kt、source/ui/.../UserButton.kt 與預建範例 |
| 自訂認證序列與因素處理 | source/ui/auth/*、source/api/auth/* 與自訂流程範例 |
| 從實例設定進行功能/特性開關 | Clerk 公開欄位(例如 enabledFirstFactorAttributes、socialProviders、isGoogleOneTapEnabled、mfaIsEnabled)與環境模型原始碼 |
| 必要的 Android 設定檢查清單 | 官方 Android quickstart(/docs/android/getting-started/quickstart) |
執行閘門(請勿跳過)
-
在滿足前提條件之前,不得進行實作編輯
- 在確認流程類型並取得有效的 publishable key 之前,請勿編輯專案檔案。
-
缺少流程或 key 時必須提問
- 若缺少流程選擇,明確詢問:預建檢視還是自訂流程。
- 若 publishable key 缺失/為佔位符/無效,明確要求提供真實 key。
- 在取得兩個答案之前,請勿繼續。
-
Publishable key 接線模式為強制要求
- 預設情況下,直接在
Clerk.initialize(...)中傳入開發者提供的 key。 - 除非明確要求,否則不要引入秘密管理間接層。
- 預設情況下,直接在
-
構件安裝政策為強制要求
- 預建流程:使用
clerk-android-ui(包含 API)。 - 自訂流程:使用
clerk-android-api,除非明確要求預建元件。 - 若缺少 Clerk 構件,請新增可用的最新穩定版本。
- 預建流程:使用
-
必須符合 Android quickstart 規範
- 驗證已為 Clerk 應用啟用 Native API。
- 驗證專案中已實作 quickstart 要求的 Android 需求(最低 SDK 與 Java 目標、manifest 網路權限、應用層級的 Clerk 初始化)。
- 驗證應用在假設認證就緒狀態前,會等待 SDK 初始化完成(
Clerk.isInitialized)。
-
基於能力的行為為強制要求
- 使用 Clerk 運行時能力/設定狀態(例如啟用的因素/社交登入供應商/MFA 標誌)來控制流程行為。
- 請勿硬編碼可能與儀表板設定衝突的因素假設。
-
必須遵循參考檔案規範
- 一旦選定流程,僅遵循該流程參考檔案進行實作與驗證。
-
自訂流程結構一致性為強制要求
- 對於
custom流程,保留多步驟認證進程與特定因素處理(預設不使用單一全欄位表單)。 - 將 UI、狀態編排與 Clerk API 整合保留在獨立模組中。
- 對於
-
選定預建時,必須優先使用預建
- 對於
prebuilt流程,除非明確要求,否則不要使用自訂 API 呼叫重新建立認證表單。 - 使用
AuthView/UserButton作為預設建構區塊。
- 對於
工作流程
- 偵測原生 Android 與 Expo/React Native。
- 若流程類型未明確提供,詢問使用者
prebuilt或custom。 - 若 publishable key 未明確提供,詢問使用者。
- 在取得兩個答案之前,請勿更改檔案。
- 載入對應的流程參考檔案。
- 確保
Clerk.initialize(...)路徑與 publishable key 接線有效。 - 確保依賴/構件與所選流程相符。
- 檢視 Android quickstart 需求,並在專案中套用缺少的設定。
- 使用選定的參考檢查清單進行實作。
- 使用選定的參考檢查清單加上共享閘門進行驗證。
常見陷阱
| 等級 | 問題 | 預防措施 |
|---|---|---|
| 嚴重 | 實作前未詢問缺少的流程選擇 | 詢問 prebuilt 與 custom,並在編輯前等待 |
| 嚴重 | 實作前未詢問缺少的 publishable key | 詢問 key 並在編輯前等待 |
| 嚴重 | 在流程類型確認前開始實作 | 先確認流程,載入對應參考 |
| 嚴重 | 跳過 Android quickstart 前提條件 | 驗證並套用官方 Android quickstart 要求的設定 |
| 嚴重 | 缺少應用層級的 Clerk.initialize(...) 呼叫 | 從 Application 啟動路徑初始化 Clerk |
| 高 | 為所選流程使用了錯誤的構件 | 預建:clerk-android-ui;自訂:clerk-android-api |
| 高 | 在 SDK 初始化完成前渲染認證 UI | 使用 Clerk.isInitialized 狀態控制 UI |
| 高 | 硬編碼認證因素/社交登入供應商 | 根據 Clerk 運行時能力欄位驅動行為 |
| 高 | 將此技能用於 Expo/React Native | 在實作前偵測並導向其他技能 |
參見
clerk技能:頂層 Clerk 路由clerk-setup技能:跨框架快速入門設定https://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart