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 快速入门并验证所需设置(Native API、最低 SDK/Java、清单、初始化) |
| 6 | 检查与所选流程相关的 clerk-android 源码/示例模式 |
| 7 | 严格遵循所选参考清单实现流程 |
决策树
用户请求在 Android/Kotlin 中使用 Clerk
|
+-- 检测到 Expo/React Native 项目?
| |
| +-- 是 -> 不使用此技能
| |
| +-- 否 -> 继续
|
+-- 检测到现有认证 UI?
| |
| +-- 检测到预置视图 -> 加载 references/prebuilt.md
| |
| +-- 检测到自定义流程 -> 加载 references/custom.md
| |
| +-- 新实现 -> 询问开发者选择预置/自定义,然后加载对应参考
|
+-- 确保 publishable key 和 SDK 初始化路径
|
+-- 确保安装了正确的 Android 构件
|
+-- 验证项目中符合快速入门先决条件
|
+-- 使用所选流程参考实现
流程参考
确定流程类型后,只加载其中一个:
- 预置流程:references/prebuilt.md
- 自定义流程:references/custom.md
除非开发者明确要求混合方案,否则不要在单次实现中混合使用两个参考。
交互契约
在进行任何实现编辑之前,agent 必须同时拥有:
- 流程选择:
prebuilt或custom - 一个真实的 Clerk publishable key
如果用户请求/上下文中缺少任一值:
- 向用户询问缺失的值
- 暂停并等待回答
- 在得到答案之前,不要编辑文件或安装依赖
仅当用户在当前对话中已经明确提供了该值时,才可以跳过提问。
源码驱动模板
不要在此技能中硬编码实现示例。在实现之前,检查当前已安装 SDK 版本的 clerk-android 源码/文档。
| 用例 | 信息来源 |
|---|---|
SDK 构件及依赖拆分(clerk-android-api vs clerk-android-ui) | clerk-android README 和 Android 安装文档 |
| SDK 初始化和 publishable key 连接 | 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) |
执行门控(不可跳过)
-
满足先决条件前不进行实现编辑
- 在流程类型确认并且存在有效的 publishable key 之前,不要编辑项目文件。
-
缺少流程或密钥时必须提问
- 如果缺少流程选择,明确询问:预置视图还是自定义流程。
- 如果 publishable key 缺失/为占位符/无效,明确要求提供真实密钥。
- 在两个问题的答案都提供之前,不要继续。
-
Publishable key 连接方式为强制要求
- 默认情况下,在
Clerk.initialize(...)中直接使用开发者提供的密钥。 - 除非明确要求,否则不要引入秘密管理的间接层。
- 默认情况下,在
-
构件安装策略为强制要求
- 预置流程:使用
clerk-android-ui(包含 API)。 - 自定义流程:使用
clerk-android-api,除非明确要求预置组件。 - 如果缺少 Clerk 构件,添加可用的最新稳定版本。
- 预置流程:使用
-
Android 快速入门合规性为强制要求
- 验证 Clerk 应用的 Native API 已启用。
- 验证项目中已实现快速入门中的 Android 要求(最低 SDK 和 Java 目标、清单网络权限、应用级 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 快速入门要求,并在项目中应用缺失的设置。
- 使用所选参考清单实现。
- 使用所选参考清单加上共享门控进行验证。
常见陷阱
| 等级 | 问题 | 预防措施 |
|---|---|---|
| 严重 | 实现前未询问缺失的流程选择 | 询问 prebuilt 还是 custom,在编辑前等待回答 |
| 严重 | 实现前未询问缺失的 publishable key | 询问密钥,在编辑前等待回答 |
| 严重 | 在流程类型确认前开始实现 | 先确认流程,然后加载匹配的参考 |
| 严重 | 跳过 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-androidhttps://clerk.com/docs/android/getting-started/quickstart