Clerk Android 原生集成指南：Kotlin与Jetpack Compose身份验证实现

clerk-android by clerk/skills

284 周安装量

30 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/clerk/skills --skill clerk-android

Kotlin 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 信号，请转而路由到通用设置技能。

快速开始

步骤	操作
1	确认项目类型是原生 Android 而非 Expo/React Native
2	确定流程类型（或）并加载匹配的参考文件

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

源码驱动的模板

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

用例	事实来源
SDK artifacts 和依赖项拆分（`clerk-android-api` 与 `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(...) 中。
- 除非明确要求，否则不要引入密钥管理的间接层。
artifact 安装策略是强制的
- 预构建流程：使用 clerk-android-ui（包含 API）。
- 自定义流程：除非明确请求预构建组件，否则使用 clerk-android-api。
- 如果缺少 Clerk artifacts，则添加最新的稳定版本。
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 连接有效。
确保依赖项/artifacts 与所选流程匹配。
审查 Android 快速入门要求，并在项目中应用缺失的设置。
使用所选参考清单进行实现。
使用所选参考清单加上共享关卡进行验证。

级别	问题	预防措施
CRITICAL	在实现前未询问缺失的流程选择	在编辑前询问 `prebuilt` 与 `custom` 并等待回答
CRITICAL	在实现前未询问缺失的 publishable key	在编辑前询问密钥并等待回答
CRITICAL	在确认流程类型之前开始实现	首先确认流程并加载匹配的参考
CRITICAL	跳过 Android 快速入门先决条件	验证并应用官方 Android 快速入门中所需的设置
CRITICAL	缺少应用级别的 `Clerk.initialize(...)` 调用	从 `Application` 启动路径初始化 Clerk
HIGH	为所选流程使用了错误的 artifact	预构建：`clerk-android-ui`；自定义：`clerk-android-api`
HIGH	在 SDK 初始化完成之前渲染身份验证 UI	使用 `Clerk.isInitialized` 状态控制 UI
HIGH	硬编码身份验证因素/社交提供商	根据 Clerk 运行时功能字段驱动行为
HIGH	将此技能用于 Expo/React Native	在实现之前检测并路由到其他技能

../clerk/SKILL.md 用于顶级 Clerk 路由
../setup/SKILL.md 用于跨框架快速入门设置
https://github.com/clerk/clerk-android
https://clerk.com/docs/android/getting-started/quickstart

🇺🇸English

Clerk Android (Native)

This skill implements Clerk in native Android projects by following current clerk-android SDK and docs patterns.

Activation Rules

Activate this skill when either condition is true:

The user explicitly asks for Android, Kotlin, Jetpack Compose, or native mobile Clerk implementation on Android.
The project appears to be native Android (for example build.gradle(.kts) with Android plugins, AndroidManifest.xml, app/src/main/java, Compose UI files).

Do not activate this skill when either condition is true:

The project is Expo.
The project is React Native.

If Expo/React Native signals are present, route to the general setup skill instead.

Quick Start

Step	Action
1	Confirm project type is native Android and not Expo/React Native
2	Determine flow type (`prebuilt` or `custom`) and load the matching reference file
3	Ensure a real Clerk publishable key exists (or ask developer)
4	Ensure correct Clerk artifacts are installed for the selected flow
5	Read official Android quickstart and verify required setup (Native API, min SDK/Java, manifest, initialization)
6	Inspect `clerk-android` source/sample patterns relevant to selected flow
7	Implement flow by following only the selected reference checklist

Decision Tree

User asks for Clerk in Android/Kotlin
    |
    +-- Expo/React Native project detected?
    |     |
    |     +-- YES -> Do not use this skill
    |     |
    |     +-- NO -> Continue
    |
    +-- Existing auth UI detected?
    |     |
    |     +-- Prebuilt views detected -> Load references/prebuilt.md
    |     |
    |     +-- Custom flow detected -> Load references/custom.md
    |     |
    |     +-- New implementation -> Ask developer prebuilt/custom, then load matching reference
    |
    +-- Ensure publishable key and SDK initialization path
    |
    +-- Ensure correct Android artifacts are installed
    |
    +-- Verify quickstart prerequisites in project
    |
    +-- Implement using selected flow reference

Flow References

After flow type is known, load exactly one:

Prebuilt flow: references/prebuilt.md
Custom flow: references/custom.md

Do not blend the two references in a single implementation unless the developer explicitly asks for a hybrid approach.

Interaction Contract

Before any implementation edits, the agent must have both:

flow choice: prebuilt or custom
a real Clerk publishable key

If either value is missing from the user request/context:

ask the user for the missing value(s)
pause and wait for the answer
do not edit files or install dependencies yet

Only skip asking when the user has already explicitly provided the value in this conversation.

Source-Driven Templates

Do not hardcode implementation examples in this skill. Inspect current clerk-android source/docs for the installed SDK version before implementing.

Use Case	Source of Truth
SDK artifacts and dependency split (`clerk-android-api` vs `clerk-android-ui`)	`clerk-android` README and Android install docs
SDK initialization and publishable key wiring	Android quickstart and `source/api/.../Clerk.kt`
Prebuilt auth and profile behavior	`source/ui/.../AuthView.kt`, `source/ui/.../UserButton.kt`, and prebuilt sample
Custom auth sequencing and factor handling	`source/ui/auth/*`, , and custom-flows sample

Execution Gates (Do Not Skip)

No implementation edits before prerequisites

Do not edit project files until flow type is confirmed and a valid publishable key is available.

Missing flow or key must trigger a question

If flow choice is missing, explicitly ask: prebuilt views or custom flow.
If publishable key is missing/placeholder/invalid, explicitly ask for a real key.
Do not continue until both answers are provided.

Publishable key wiring mode is mandatory

By default, wire the developer-provided key directly in Clerk.initialize(...).
Do not introduce secret-management indirection unless explicitly requested.

Artifact install policy is mandatory

Prebuilt flow: use clerk-android-ui (includes API).
Custom flow: use clerk-android-api unless prebuilt components are explicitly requested.
If Clerk artifacts are missing, add the latest stable release available.

Android quickstart compliance is mandatory

Verify Native API is enabled for the Clerk app.
Verify Android requirements from quickstart are implemented in project (minimum SDK and Java target, manifest internet permission, app-level Clerk initialization).
Verify app waits for SDK initialization (Clerk.isInitialized) before assuming auth-ready state.

Capability-driven behavior is mandatory

Use Clerk runtime capability/settings state (for example enabled factors/social providers/MFA flags) to gate flow behavior.
Do not hardcode factor assumptions that may conflict with dashboard configuration.

Reference-file discipline is mandatory

Once flow is selected, follow only that flow reference file for implementation and verification.

Custom-flow structure parity is mandatory

For custom flow, preserve multi-step auth progression and factor-specific handling (no single all-fields form by default).
Keep UI, state orchestration, and Clerk API integration in separate modules.

Prebuilt preference is mandatory when selected

For prebuilt flow, do not rebuild auth forms with custom API calls unless explicitly requested.
Use AuthView/UserButton as default building blocks.

Workflow

Detect native Android vs Expo/React Native.
If flow type is not explicitly provided, ask user for prebuilt or custom.
If publishable key is not explicitly provided, ask user for it.
Wait for both answers before changing files.
Load matching flow reference file.
Ensure Clerk.initialize(...) path and publishable key wiring are valid.
Ensure dependencies/artifacts match selected flow.
Review Android quickstart requirements and apply missing setup in project.
Implement using selected reference checklist.
Verify using selected reference checklist plus shared gates.

Common Pitfalls

Level	Issue	Prevention
CRITICAL	Not asking for missing flow choice before implementation	Ask for `prebuilt` vs `custom` and wait before edits
CRITICAL	Not asking for missing publishable key before implementation	Ask for key and wait before edits
CRITICAL	Starting implementation before flow type is confirmed	Confirm flow first and load matching reference
CRITICAL	Skipping Android quickstart prerequisites	Verify and apply required setup from official Android quickstart
CRITICAL	Missing app-level `Clerk.initialize(...)` call	Initialize Clerk from `Application` startup path

Clerk Android 原生集成指南：Kotlin与Jetpack Compose身份验证实现

🇨🇳中文介绍

Clerk Android（原生）

激活规则

快速开始

相关 Skills

决策树

流程参考

交互契约