clerk-android

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 可发布密钥（或询问开发者）
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
    |     |
    |     +-- 新实现 -> 询问开发者预构建/自定义，然后加载对应参考
    |
    +-- 确保可发布密钥和 SDK 初始化路径
    |
    +-- 确保安装了正确的 Android 构件
    |
    +-- 验证项目中的快速入门先决条件
    |
    +-- 使用所选流程参考实现

流程参考

确定流程类型后，仅加载一个：

• 预构建流程： references/prebuilt.md
• 自定义流程： references/custom.md

除非开发者明确要求混合方法，否则不要在单个实现中混合两个参考。

交互契约

在进行任何实现编辑之前，代理必须同时拥有：

• 流程选择：prebuilt 或 custom
• 真实的 Clerk 可发布密钥

如果用户请求/上下文中缺少任一值：

• 询问用户缺失的值
• 暂停并等待回答
• 不要编辑文件或安装依赖项

仅当用户已在此对话中明确提供该值时，才可跳过询问。

源码驱动模板

不要在本技能中硬编码实现示例。在实现之前，检查当前已安装 SDK 版本的 clerk-android 源码/文档。

用例	事实来源
SDK 构件和依赖拆分（clerk-android-api 与 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 目标、清单互联网权限、应用级 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