clerk-android

Clerk Android (原生)

此技能透過遵循目前的 clerk-android SDK 和文件模式，在原生 Android 專案中實作 Clerk。

啟用規則

當以下任一條件成立時啟用此技能：

• 使用者明確要求 Android、Kotlin、Jetpack Compose 或 Android 上的原生行動 Clerk 實作。
• 專案看起來是原生 Android（例如 build.gradle(.kts) 包含 Android 外掛、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 可發布金鑰（或詢問開發者）
4	確保為所選流程安裝正確的 Clerk 成品
5	閱讀官方 Android 快速入門並驗證必要的設定（Native API、最低 SDK/Java、manifest、初始化）
6	檢查與所選流程相關的 clerk-android 原始碼/範例模式
7	僅遵循所選的參考檢查清單來實作流程

決策樹

使用者要求 Android/Kotlin 的 Clerk
    |
    +-- 偵測到 Expo/React Native 專案？
    |     |
    |     +-- 是 -> 不使用此技能
    |     |
    |     +-- 否 -> 繼續
    |
    +-- 偵測到現有認證 UI？
    |     |
    |     +-- 偵測到預先建置的視圖 -> 載入 references/prebuilt.md
    |     |
    |     +-- 偵測到自訂流程 -> 載入 references/custom.md
    |     |
    |     +-- 新的實作 -> 詢問開發者預先建置或自訂，然後載入對應的參考
    |
    +-- 確保可發布金鑰和 SDK 初始化路徑
    |
    +-- 確保安裝正確的 Android 成品
    |
    +-- 驗證專案中的快速入門先決條件
    |
    +-- 使用所選流程參考進行實作

流程參考

在確定流程類型後，僅載入一個：

• 預先建置流程：references/prebuilt.md
• 自訂流程：references/custom.md

除非開發者明確要求混合方法，否則不要在單一實作中混合使用兩個參考。

互動合約

在進行任何實作編輯之前，代理必須同時擁有：

• 流程選擇：prebuilt 或 custom
• 一個真實的 Clerk 可發布金鑰

如果使用者請求/情境中缺少任一值：

• 詢問使用者缺少的值
• 暫停並等待回答
• 不要編輯檔案或安裝相依性

僅當使用者在本次對話中已明確提供該值時，才可跳過詢問。

原始碼驅動的範本

不要在此技能中硬編碼實作範例。在實作之前，檢查目前安裝的 SDK 版本的 clerk-android 原始碼/文件。

使用案例	真相來源
SDK 成品和相依性拆分（clerk-android-api vs clerk-android-ui）	clerk-android README 和 Android 安裝文件
SDK 初始化和可發布金鑰連接	Android 快速入門和 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 快速入門（/docs/android/getting-started/quickstart）

執行閘門（不可跳過）

1. 在滿足先決條件之前不進行實作編輯

• 在確認流程類型並取得有效的可發布金鑰之前，不要編輯專案檔案。

2. 缺少流程或金鑰必須觸發問題

• 如果缺少流程選擇，明確詢問：預先建置視圖或自訂流程。
• 如果可發布金鑰缺失/為佔位符/無效，明確詢問真實金鑰。
• 在提供兩個答案之前不要繼續。

3. 可發布金鑰連接模式是強制的

• 預設情況下，直接將開發者提供的金鑰連接到 Clerk.initialize(...)。
• 除非明確要求，否則不要引入秘密管理間接層。

4. 成品安裝政策是強制的

• 預先建置流程：使用 clerk-android-ui（包含 API）。
• 自訂流程：使用 clerk-android-api，除非明確要求預先建置元件。
• 如果缺少 Clerk 成品，請新增可用的最新穩定版本。

5. Android 快速入門合規性是強制的

• 確認 Clerk 應用程式已啟用 Native API。
• 確認專案中已實作快速入門中的 Android 需求（最低 SDK 和 Java 目標、manifest 網路權限、應用程式層級的 Clerk 初始化）。
• 確認應用程式在假設認證就緒狀態之前等待 SDK 初始化完成（Clerk.isInitialized）。

6. 功能驅動的行為是強制的

• 使用 Clerk 執行時期功能/設定狀態（例如啟用的因素/社交提供者/MFA 旗標）來控制流程行為。
• 不要硬編碼可能與儀表板設定衝突的因素假設。

7. 參考檔案紀律是強制的

• 一旦選定流程，僅遵循該流程參考檔案進行實作和驗證。

8. 自訂流程結構一致性是強制的

• 對於 custom 流程，保留多步驟認證進度和特定因素處理（預設不使用單一全欄位表單）。
• 將 UI、狀態編排和 Clerk API 整合保持在單獨的模組中。

9. 選定時偏好預先建置是強制的

• 對於 prebuilt 流程，除非明確要求，否則不要使用自訂 API 呼叫重建認證表單。
• 預設使用 AuthView/UserButton 作為建構區塊。

工作流程

1. 偵測原生 Android 與 Expo/React Native。
2. 如果未明確提供流程類型，詢問使用者 prebuilt 或 custom。
3. 如果未明確提供可發布金鑰，詢問使用者。
4. 在變更檔案之前等待兩個答案。
5. 載入對應的流程參考檔案。
6. 確保 Clerk.initialize(...) 路徑和可發布金鑰連接有效。
7. 確保相依性/成品與所選流程匹配。
8. 檢視 Android 快速入門需求並在專案中套用缺少的設定。
9. 使用所選參考檢查清單進行實作。
10. 使用所選參考檢查清單加上共用閘門進行驗證。

常見陷阱

等級	問題	預防措施
嚴重	在實作前未詢問缺少的流程選擇	詢問 prebuilt 與 custom 並在編輯前等待
嚴重	在實作前未詢問缺少的可發布金鑰	詢問金鑰並在編輯前等待
嚴重	在確認流程類型前開始實作	先確認流程並載入對應參考
嚴重	跳過 Android 快速入門先決條件	從官方 Android 快速入門驗證並套用必要設定
嚴重	缺少應用程式層級的 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-android
• https://clerk.com/docs/android/getting-started/quickstart