Back to Details

clerk-android

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Clerk Android (Native)

Clerk Android（原生）

This skill implements Clerk in native Android projects by following current 
clerk-android
SDK and docs patterns.
本技能遵循当前
clerk-android
SDK和文档模式，在原生Android项目中集成Clerk。

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.
满足以下任一条件时激活本技能：
  • 用户明确询问在Android上使用Kotlin、Jetpack Compose或原生移动应用的Clerk实现方案。
  • 项目为原生Android类型（例如包含带Android插件的
    build.gradle(.kts)
    、
    AndroidManifest.xml
    、
    app/src/main/java
    、Compose UI文件）。
满足以下任一条件时请勿激活本技能：
  • 项目为Expo类型。
  • 项目为React Native类型。
如果检测到Expo/React Native相关特征，应转至通用设置技能处理。

Quick Start

快速开始

StepAction
1Confirm project type is native Android and not Expo/React Native
2Determine flow type (
prebuilt
or 
custom
) and load the matching reference file
3Ensure a real Clerk publishable key exists (or ask developer)
4Ensure correct Clerk artifacts are installed for the selected flow
5Read official Android quickstart and verify required setup (Native API, min SDK/Java, manifest, initialization)
6Inspect 
clerk-android
source/sample patterns relevant to selected flow
7Implement flow by following only the selected reference checklist
步骤操作
1确认项目类型为原生Android，而非Expo/React Native
2确定流程类型（
prebuilt
或
custom
）并加载对应的参考文件
3确保存在有效的Clerk发布密钥（或向开发者索要）
4确保为所选流程安装了正确的Clerk组件
5阅读官方Android快速入门指南，验证所需的设置（Native API、最低SDK/Java版本、清单文件、初始化配置）
6检查与所选流程相关的
clerk-android
源码/示例模式
7仅遵循所选参考清单实现流程

Decision Tree

决策树

text
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
text
用户询问Android/Kotlin中的Clerk集成
    |
    +-- 检测到Expo/React Native项目？
    |     |
    |     +-- 是 -> 不使用本技能
    |     |
    |     +-- 否 -> 继续
    |
    +-- 检测到现有认证UI？
    |     |
    |     +-- 检测到预构建视图 -> 加载references/prebuilt.md
    |     |
    |     +-- 检测到自定义流程 -> 加载references/custom.md
    |     |
    |     +-- 新实现 -> 询问开发者选择预构建/自定义流程，然后加载对应参考
    |
    +-- 确保发布密钥和SDK初始化路径正确
    |
    +-- 确保安装了正确的Android组件
    |
    +-- 验证项目中的快速入门前置条件
    |
    +-- 使用所选流程参考进行实现

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.
确定流程类型后，仅加载以下其中一个参考：
  • 预构建流程：references/prebuilt.md
  • 自定义流程：references/custom.md
除非开发者明确要求混合方案，否则请勿在单次实现中混合使用两个参考的内容。

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.
在进行任何实现编辑之前，代理必须同时确认：
  • 流程选择：
    prebuilt
    或
    custom
  • 有效的Clerk发布密钥
如果用户请求/上下文缺少任一值：
  • 向用户询问缺失的值
  • 暂停操作等待回复
  • 暂不编辑文件或安装依赖
仅当用户在本次对话中已明确提供对应值时，才可跳过询问步骤。

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 CaseSource 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 wiringAndroid 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/*
, 
source/api/auth/*
, and custom-flows sample
Capability/feature gating from instance settings
Clerk
public fields (for example 
enabledFirstFactorAttributes
, 
socialProviders
, 
isGoogleOneTapEnabled
, 
mfaIsEnabled
) and environment model source
Required Android setup checklistOfficial Android quickstart (
/docs/android/getting-started/quickstart
)
请勿在本技能中硬编码实现示例。在实现前，请检查当前已安装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
）

Execution Gates (Do Not Skip)

执行限制（请勿跳过）

  1. No implementation edits before prerequisites
  • Do not edit project files until flow type is confirmed and a valid publishable key is available.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. Reference-file discipline is mandatory
  • Once flow is selected, follow only that flow reference file for implementation and verification.
  1. 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.
  1. 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.
  1. 前置条件未满足前请勿进行实现编辑
  • 确认流程类型并获取有效发布密钥前，请勿编辑项目文件。
  1. 缺失流程或密钥必须触发询问
  • 如果缺少流程选择，明确询问：使用预构建视图还是自定义流程。
  • 如果发布密钥缺失/为占位符/无效，明确索要真实密钥。
  • 必须获取两个问题的回复后才可继续。
  1. 必须配置发布密钥
  • 默认情况下，直接在
    Clerk.initialize(...)
    中配置开发者提供的密钥。
  • 除非明确要求，否则请勿引入密钥管理的间接方式。
  1. 必须遵循组件安装规则
  • 预构建流程：使用
    clerk-android-ui
    （包含API）。
  • 自定义流程：使用
    clerk-android-api
    ，除非明确要求使用预构建组件。
  • 如果缺少Clerk组件，添加可用的最新稳定版本。
  1. 必须符合Android快速入门指南要求
  • 验证Clerk应用已启用Native API。
  • 验证项目已实现快速入门指南中的Android要求（最低SDK和Java目标版本、清单文件中的网络权限、应用级Clerk初始化）。
  • 验证应用在SDK初始化完成（
    Clerk.isInitialized
    ）后才进入认证就绪状态。
  1. 必须基于功能特性驱动行为
  • 使用Clerk运行时功能/设置状态（例如启用的因子/社交登录提供商/MFA标志）管控流程行为。
  • 请勿硬编码可能与控制台配置冲突的认证因子假设。
  1. 必须遵循参考文件规范
  • 选择流程后，仅遵循该流程的参考文件进行实现和验证。
  1. 自定义流程结构必须一致
  • 对于
    custom
    流程，保留多步骤认证流程和特定因子处理逻辑（默认不使用单一包含所有字段的表单）。
  • 将UI、状态编排和Clerk API集成放在独立模块中。
  1. 选择预构建流程后必须优先使用预构建组件
  • 对于
    prebuilt
    流程，除非明确要求，否则请勿使用自定义API调用重新构建认证表单。
  • 默认使用
    AuthView
    /
    UserButton
    作为构建块。

Workflow

工作流程

  1. Detect native Android vs Expo/React Native.
  2. If flow type is not explicitly provided, ask user for 
    prebuilt
    or 
    custom
    .
  3. If publishable key is not explicitly provided, ask user for it.
  4. Wait for both answers before changing files.
  5. Load matching flow reference file.
  6. Ensure 
    Clerk.initialize(...)
    path and publishable key wiring are valid.
  7. Ensure dependencies/artifacts match selected flow.
  8. Review Android quickstart requirements and apply missing setup in project.
  9. Implement using selected reference checklist.
  10. Verify using selected reference checklist plus shared gates.
  1. 检测项目是原生Android还是Expo/React Native。
  2. 如果未明确提供流程类型，询问用户选择
    prebuilt
    或
    custom
    。
  3. 如果未明确提供发布密钥，向用户索要。
  4. 获取两个回复后再修改文件。
  5. 加载匹配的流程参考文件。
  6. 确保
    Clerk.initialize(...)
    路径和发布密钥配置有效。
  7. 确保依赖/组件与所选流程匹配。
  8. 检查Android快速入门指南的要求，在项目中补全缺失的设置。
  9. 遵循所选参考清单进行实现。
  10. 使用所选参考清单和共享限制进行验证。

Common Pitfalls

常见陷阱

LevelIssuePrevention
CRITICALNot asking for missing flow choice before implementationAsk for 
prebuilt
vs 
custom
and wait before edits
CRITICALNot asking for missing publishable key before implementationAsk for key and wait before edits
CRITICALStarting implementation before flow type is confirmedConfirm flow first and load matching reference
CRITICALSkipping Android quickstart prerequisitesVerify and apply required setup from official Android quickstart
CRITICALMissing app-level 
Clerk.initialize(...)
call		Initialize Clerk from 
Application
startup path
HIGHWrong artifact for chosen flowPrebuilt: 
clerk-android-ui
; custom: 
clerk-android-api
HIGHRendering auth UI before SDK initialization completesGate UI with 
Clerk.isInitialized
state
HIGHHardcoding auth factors/social providersDrive behavior from Clerk runtime capability fields
HIGHUsing this skill for Expo/React NativeDetect and route away before implementation
级别问题预防措施
严重实现前未询问缺失的流程选择先询问
prebuilt
或
custom
，等待回复后再编辑
严重实现前未询问缺失的发布密钥索要密钥，等待回复后再编辑
严重未确认流程类型就开始实现先确认流程类型，再加载对应参考
严重跳过Android快速入门前置条件验证并应用官方Android快速入门指南中的必需设置
严重缺少应用级
Clerk.initialize(...)
调用		从
Application
启动路径初始化Clerk
高为所选流程安装了错误的组件预构建流程：使用
clerk-android-ui
；自定义流程：使用
clerk-android-api
高SDK初始化完成前渲染认证UI使用
Clerk.isInitialized
状态管控UI渲染
高硬编码认证因子/社交登录提供商基于Clerk运行时功能字段驱动行为
高将本技能用于Expo/React Native项目检测到后转至其他技能处理，不进行实现

See Also

另请参阅

  • ../clerk/SKILL.md
    for top-level Clerk routing
  • ../setup/SKILL.md
    for cross-framework quickstart setup
  • https://github.com/clerk/clerk-android
  • https://clerk.com/docs/android/getting-started/quickstart
  • ../clerk/SKILL.md
    顶级Clerk路由
  • ../setup/SKILL.md
    跨框架快速入门设置
  • https://github.com/clerk/clerk-android
  • https://clerk.com/docs/android/getting-started/quickstart