Clerk Android (Nativo)
Esta habilidad implementa Clerk en proyectos Android nativos siguiendo los patrones actuales del SDK clerk-android y su documentación.
Reglas de Activación
Activa esta habilidad cuando se cumpla cualquier condición:
- El usuario pide explícitamente una implementación de Clerk para Android, Kotlin, Jetpack Compose o móvil nativo en Android.
- El proyecto parece ser Android nativo (por ejemplo,
build.gradle(.kts)con plugins de Android,AndroidManifest.xml,app/src/main/java, archivos de UI Compose).
No actives esta habilidad cuando se cumpla cualquier condición:
- El proyecto es Expo.
- El proyecto es React Native.
Si se detectan señales de Expo/React Native, redirige a la habilidad de configuración general.
¿Qué Necesitas?
| Tarea | Referencia |
|---|---|
| AuthView / UserButton predefinidos (más rápido) | references/prebuilt.md |
| Flujos de autenticación personalizados basados en API (control total) | references/custom.md |
Inicio Rápido
| Paso | Acción |
|---|---|
| 1 | Confirmar que el tipo de proyecto es Android nativo y no Expo/React Native |
| 2 | Determinar el tipo de flujo (prebuilt o custom) y cargar el archivo de referencia correspondiente |
| 3 | Asegurar que existe una clave publicable real de Clerk (o preguntar al desarrollador) |
| 4 | Asegurar que los artefactos correctos de Clerk están instalados para el flujo seleccionado |
| 5 | Leer la guía de inicio rápido oficial de Android y verificar la configuración requerida (API nativa, SDK mínimo/Java, manifiesto, inicialización) |
| 6 | Inspeccionar las fuentes/ejemplos de clerk-android relevantes para el flujo seleccionado |
| 7 | Implementar el flujo siguiendo exclusivamente la lista de verificación de la referencia seleccionada |
Árbol de Decisión
El usuario pide Clerk en Android/Kotlin
|
+-- ¿Se detectó proyecto Expo/React Native?
| |
| +-- SÍ -> No usar esta habilidad
| |
| +-- NO -> Continuar
|
+-- ¿Se detectó UI de autenticación existente?
| |
| +-- Vistas predefinidas detectadas -> Cargar references/prebuilt.md
| |
| +-- Flujo personalizado detectado -> Cargar references/custom.md
| |
| +-- Nueva implementación -> Preguntar al desarrollador prebuilt/custom, luego cargar referencia correspondiente
|
+-- Asegurar clave publicable y ruta de inicialización del SDK
|
+-- Asegurar que los artefactos correctos de Android están instalados
|
+-- Verificar requisitos previos de la guía de inicio rápido en el proyecto
|
+-- Implementar usando la referencia del flujo seleccionado
Referencias de Flujo
Una vez conocido el tipo de flujo, cargar exactamente una:
- Flujo predefinido: references/prebuilt.md
- Flujo personalizado: references/custom.md
No mezclar las dos referencias en una sola implementación a menos que el desarrollador lo solicite explícitamente.
Contrato de Interacción
Antes de cualquier edición de implementación, el agente debe tener ambos:
- elección de flujo:
prebuiltocustom - una clave publicable real de Clerk
Si falta cualquiera de los valores en la solicitud/contexto del usuario:
- preguntar al usuario por el/los valor(es) faltante(s)
- pausar y esperar la respuesta
- no editar archivos ni instalar dependencias todavía
Solo omitir la pregunta cuando el usuario ya haya proporcionado explícitamente el valor en esta conversación.
Plantillas Basadas en Código Fuente
No codifiques ejemplos de implementación fijos en esta habilidad. Inspecciona las fuentes/documentación actuales de clerk-android para la versión instalada del SDK antes de implementar.
| Caso de Uso | Fuente de Verdad |
|---|---|
Artefactos del SDK y división de dependencias (clerk-android-api vs clerk-android-ui) | README de clerk-android y documentos de instalación de Android |
| Inicialización del SDK y configuración de la clave publicable | Guía de inicio rápido de Android y source/api/.../Clerk.kt |
| Comportamiento de autenticación y perfil predefinidos | source/ui/.../AuthView.kt, source/ui/.../UserButton.kt y ejemplo predefinido |
| Secuenciación de autenticación personalizada y manejo de factores | source/ui/auth/*, source/api/auth/* y ejemplo de flujos personalizados |
| Control de capacidades/funcionalidades desde la configuración de la instancia | Campos públicos de Clerk (por ejemplo enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) y modelo de entorno fuente |
| Lista de verificación de configuración requerida de Android | Guía de inicio rápido oficial de Android (/docs/android/getting-started/quickstart) |
Puertas de Ejecución (No Omitir)
-
No editar implementación antes de los prerrequisitos
- No editar archivos del proyecto hasta que el tipo de flujo esté confirmado y haya una clave publicable válida disponible.
-
Flujo o clave faltantes deben generar una pregunta
- Si falta la elección del flujo, preguntar explícitamente: ¿vistas predefinidas o flujo personalizado?
- Si la clave publicable falta, es un marcador de posición o no es válida, preguntar explícitamente por una clave real.
- No continuar hasta que ambas respuestas estén dadas.
-
El modo de configuración de la clave publicable es obligatorio
- Por defecto, conectar la clave proporcionada por el desarrollador directamente en
Clerk.initialize(...). - No introducir indirección de gestión de secretos a menos que se solicite explícitamente.
- Por defecto, conectar la clave proporcionada por el desarrollador directamente en
-
La política de instalación de artefactos es obligatoria
- Flujo predefinido: usar
clerk-android-ui(incluye API). - Flujo personalizado: usar
clerk-android-apia menos que se soliciten explícitamente componentes predefinidos. - Si faltan artefactos de Clerk, agregar la última versión estable disponible.
- Flujo predefinido: usar
-
El cumplimiento de la guía de inicio rápido de Android es obligatorio
- Verificar que la API nativa esté habilitada para la aplicación Clerk.
- Verificar que los requisitos de Android de la guía de inicio rápido estén implementados en el proyecto (SDK mínimo y objetivo de Java, permiso de Internet en el manifiesto, inicialización de Clerk a nivel de aplicación).
- Verificar que la aplicación espere la inicialización del SDK (
Clerk.isInitialized) antes de asumir el estado listo para autenticación.
-
El comportamiento basado en capacidades es obligatorio
- Usar el estado de capacidades/configuración en tiempo de ejecución de Clerk (por ejemplo, factores habilitados/proveedores sociales/marcas MFA) para controlar el comportamiento del flujo.
- No codificar suposiciones de factores que puedan entrar en conflicto con la configuración del panel de control.
-
La disciplina del archivo de referencia es obligatoria
- Una vez seleccionado el flujo, seguir solo ese archivo de referencia de flujo para la implementación y verificación.
-
La paridad de estructura del flujo personalizado es obligatoria
- Para el flujo
custom, preservar la progresión de autenticación en varios pasos y el manejo específico de factores (sin un formulario único de todos los campos por defecto). - Mantener la UI, la orquestación de estado y la integración con la API de Clerk en módulos separados.
- Para el flujo
-
La preferencia por el flujo predefinido es obligatoria cuando se selecciona
- Para el flujo
prebuilt, no reconstruir formularios de autenticación con llamadas API personalizadas a menos que se solicite explícitamente. - Usar
AuthView/UserButtoncomo bloques de construcción predeterminados.
- Para el flujo
Flujo de Trabajo
- Detectar Android nativo vs Expo/React Native.
- Si el tipo de flujo no está explícitamente proporcionado, preguntar al usuario por
prebuiltocustom. - Si la clave publicable no está explícitamente proporcionada, preguntar al usuario por ella.
- Esperar ambas respuestas antes de cambiar archivos.
- Cargar el archivo de referencia del flujo correspondiente.
- Asegurar que la ruta de
Clerk.initialize(...)y la configuración de la clave publicable sean válidas. - Asegurar que las dependencias/artefactos coincidan con el flujo seleccionado.
- Revisar los requisitos de la guía de inicio rápido de Android y aplicar la configuración faltante en el proyecto.
- Implementar usando la lista de verificación de la referencia seleccionada.
- Verificar usando la lista de verificación de la referencia seleccionada más las puertas compartidas.
Errores Comunes
| Nivel | Problema | Prevención |
|---|---|---|
| CRÍTICO | No preguntar por la elección del flujo faltante antes de la implementación | Preguntar por prebuilt vs custom y esperar antes de editar |
| CRÍTICO | No preguntar por la clave publicable faltante antes de la implementación | Preguntar por la clave y esperar antes de editar |
| CRÍTICO | Empezar la implementación antes de confirmar el tipo de flujo | Confirmar el flujo primero y cargar la referencia correspondiente |
| CRÍTICO | Omitir los prerrequisitos de la guía de inicio rápido de Android | Verificar y aplicar la configuración requerida de la guía de inicio rápido oficial de Android |
| CRÍTICO | Falta la llamada a Clerk.initialize(...) a nivel de aplicación | Inicializar Clerk desde la ruta de inicio de Application |
| ALTO | Artefacto incorrecto para el flujo elegido | Predefinido: clerk-android-ui; personalizado: clerk-android-api |
| ALTO | Renderizar la UI de autenticación antes de que se complete la inicialización del SDK | Proteger la UI con el estado Clerk.isInitialized |
| ALTO | Codificar fijamente factores de autenticación/proveedores sociales | Guiar el comportamiento desde los campos de capacidad en tiempo de ejecución de Clerk |
| ALTO | Usar esta habilidad para Expo/React Native | Detectar y redirigir antes de la implementación |
Ver También
- Habilidad
clerkpara el enrutamiento general de Clerk - Habilidad
clerk-setuppara la configuración de inicio rápido entre marcos https://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart