Clerk Android (Nativo)
Esta skill implementa o Clerk em projetos Android nativos seguindo os padrões atuais do SDK e da documentação do clerk-android.
Regras de Ativação
Ative esta skill quando qualquer condição for verdadeira:
- O usuário pedir explicitamente por implementação Clerk no Android, Kotlin, Jetpack Compose ou mobile nativo no Android.
- O projeto parecer ser Android nativo (por exemplo
build.gradle(.kts)com plugins Android,AndroidManifest.xml,app/src/main/java, arquivos de UI Compose).
Não ative esta skill quando qualquer condição for verdadeira:
- O projeto é Expo.
- O projeto é React Native.
Se houver sinais de Expo/React Native, roteie para a skill de configuração geral.
O que você precisa?
| Tarefa | Referência |
|---|---|
| AuthView / UserButton pré-construídos (mais rápido) | references/prebuilt.md |
| Fluxos personalizados baseados em API (controle total) | references/custom.md |
Início Rápido
| Passo | Ação |
|---|---|
| 1 | Confirme que o tipo de projeto é Android nativo e não Expo/React Native |
| 2 | Determine o tipo de fluxo (prebuilt ou custom) e carregue o arquivo de referência correspondente |
| 3 | Garanta que existe uma chave pública real do Clerk (ou peça ao desenvolvedor) |
| 4 | Garanta que os artefatos corretos do Clerk estejam instalados para o fluxo selecionado |
| 5 | Leia o guia de início rápido oficial do Android e verifique a configuração necessária (API nativa, SDK mínimo/Java, manifesto, inicialização) |
| 6 | Inspecione os padrões de código-fonte e exemplos do clerk-android relevantes ao fluxo selecionado |
| 7 | Implemente o fluxo seguindo apenas a lista de verificação da referência selecionada |
Árvore de Decisão
Usuário pede Clerk em Android/Kotlin
|
+-- Projeto Expo/React Native detectado?
| |
| +-- SIM -> Não use esta skill
| |
| +-- NÃO -> Continue
|
+-- UI de autenticação existente detectada?
| |
| +-- Visualizações pré-construídas detectadas -> Carregue references/prebuilt.md
| |
| +-- Fluxo personalizado detectado -> Carregue references/custom.md
| |
| +-- Nova implementação -> Pergunte ao desenvolvedor prebuilt/custom, depois carregue a referência correspondente
|
+-- Garanta chave pública e caminho de inicialização do SDK
|
+-- Garanta que os artefatos corretos do Android estejam instalados
|
+-- Verifique pré-requisitos do guia de início rápido no projeto
|
+-- Implemente usando a referência do fluxo selecionado
Referências de Fluxo
Após o tipo de fluxo ser conhecido, carregue exatamente um:
- Fluxo pré-construído: references/prebuilt.md
- Fluxo personalizado: references/custom.md
Não misture as duas referências em uma única implementação, a menos que o desenvolvedor peça explicitamente uma abordagem híbrida.
Contrato de Interação
Antes de qualquer edição de implementação, o agente deve ter ambos:
- escolha de fluxo:
prebuiltoucustom - uma chave pública real do Clerk
Se algum valor estiver faltando na solicitação/contexto do usuário:
- pergunte ao usuário pelo(s) valor(es) faltante(s)
- pause e aguarde a resposta
- não edite arquivos nem instale dependências ainda
Apenas pule a pergunta quando o usuário já tiver fornecido o valor explicitamente nesta conversa.
Modelos Baseados em Código Fonte
Não codifique exemplos de implementação nesta skill. Inspecione o código-fonte e a documentação atuais do clerk-android para a versão do SDK instalada antes de implementar.
| Caso de Uso | Fonte da Verdade |
|---|---|
Artefatos do SDK e divisão de dependências (clerk-android-api vs clerk-android-ui) | README do clerk-android e documentação de instalação do Android |
| Inicialização do SDK e configuração da chave pública | Guia de início rápido do Android e source/api/.../Clerk.kt |
| Comportamento de autenticação e perfil pré-construídos | source/ui/.../AuthView.kt, source/ui/.../UserButton.kt e exemplo pré-construído |
| Sequenciamento de autenticação personalizada e tratamento de fatores | source/ui/auth/*, source/api/auth/* e exemplo de fluxos personalizados |
| Restrição de recursos/configurações das configurações da instância | Campos públicos do Clerk (por exemplo enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) e modelo de ambiente |
| Lista de verificação de configuração necessária do Android | Guia de início rápido oficial do Android (/docs/android/getting-started/quickstart) |
Portões de Execução (Não Pule)
-
Nenhuma edição de implementação antes dos pré-requisitos
- Não edite arquivos do projeto até que o tipo de fluxo seja confirmado e uma chave pública válida esteja disponível.
-
Fluxo ou chave ausentes devem gerar uma pergunta
- Se a escolha do fluxo estiver faltando, pergunte explicitamente: visualizações pré-construídas ou fluxo personalizado.
- Se a chave pública estiver faltando, for um placeholder ou inválida, peça explicitamente uma chave real.
- Não continue até que ambas as respostas sejam fornecidas.
-
O modo de configuração da chave pública é obrigatório
- Por padrão, insira a chave fornecida pelo desenvolvedor diretamente em
Clerk.initialize(...). - Não introduza indireção de gerenciamento de segredos, a menos que explicitamente solicitado.
- Por padrão, insira a chave fornecida pelo desenvolvedor diretamente em
-
A política de instalação de artefatos é obrigatória
- Fluxo pré-construído: use
clerk-android-ui(inclui API). - Fluxo personalizado: use
clerk-android-api, a menos que componentes pré-construídos sejam explicitamente solicitados. - Se os artefatos do Clerk estiverem ausentes, adicione a versão estável mais recente disponível.
- Fluxo pré-construído: use
-
A conformidade com o guia de início rápido do Android é obrigatória
- Verifique se a API nativa está ativada para o aplicativo Clerk.
- Verifique se os requisitos do Android do guia de início rápido estão implementados no projeto (SDK mínimo e alvo Java, permissão de internet no manifesto, inicialização do Clerk no nível do aplicativo).
- Verifique se o aplicativo aguarda a inicialização do SDK (
Clerk.isInitialized) antes de assumir o estado pronto para autenticação.
-
O comportamento orientado por capacidade é obrigatório
- Use o estado de capacidade/configurações em tempo de execução do Clerk (por exemplo fatores ativados/provedores sociais/sinalizadores MFA) para controlar o comportamento do fluxo.
- Não codifique suposições de fatores que possam entrar em conflito com a configuração do painel.
-
A disciplina do arquivo de referência é obrigatória
- Uma vez que o fluxo é selecionado, siga apenas o arquivo de referência desse fluxo para implementação e verificação.
-
A paridade da estrutura do fluxo personalizado é obrigatória
- Para fluxo
custom, preserve a progressão de autenticação em várias etapas e o tratamento específico de fatores (sem formulário único de todos os campos por padrão). - Mantenha UI, orquestração de estado e integração com API do Clerk em módulos separados.
- Para fluxo
-
A preferência por pré-construído é obrigatória quando selecionada
- Para fluxo
prebuilt, não reconstrua formulários de autenticação com chamadas de API personalizadas, a menos que explicitamente solicitado. - Use
AuthView/UserButtoncomo blocos de construção padrão.
- Para fluxo
Fluxo de Trabalho
- Detecte Android nativo vs Expo/React Native.
- Se o tipo de fluxo não for fornecido explicitamente, pergunte ao usuário por
prebuiltoucustom. - Se a chave pública não for fornecida explicitamente, pergunte ao usuário por ela.
- Aguarde ambas as respostas antes de alterar arquivos.
- Carregue o arquivo de referência do fluxo correspondente.
- Garanta que o caminho
Clerk.initialize(...)e a configuração da chave pública sejam válidos. - Garanta que dependências/artefatos correspondam ao fluxo selecionado.
- Revise os requisitos do guia de início rápido do Android e aplique a configuração ausente no projeto.
- Implemente usando a lista de verificação da referência selecionada.
- Verifique usando a lista de verificação da referência selecionada mais os portões compartilhados.
Armadilhas Comuns
| Nível | Problema | Prevenção |
|---|---|---|
| CRÍTICO | Não perguntar pela escolha de fluxo ausente antes da implementação | Pergunte por prebuilt vs custom e espere antes de editar |
| CRÍTICO | Não perguntar pela chave pública ausente antes da implementação | Pergunte pela chave e espere antes de editar |
| CRÍTICO | Iniciar implementação antes do tipo de fluxo ser confirmado | Confirme o fluxo primeiro e carregue a referência correspondente |
| CRÍTICO | Pular pré-requisitos do guia de início rápido do Android | Verifique e aplique a configuração necessária do guia de início rápido oficial do Android |
| CRÍTICO | Falta da chamada Clerk.initialize(...) no nível do aplicativo | Inicialize o Clerk a partir do caminho de inicialização do Application |
| ALTO | Artefato errado para o fluxo escolhido | Pré-construído: clerk-android-ui; personalizado: clerk-android-api |
| ALTO | Renderizar UI de autenticação antes da inicialização do SDK ser concluída | Bloqueie a UI com o estado Clerk.isInitialized |
| ALTO | Codificar fatores de autenticação/provedores sociais | Direcione o comportamento a partir dos campos de capacidade em tempo de execução do Clerk |
| ALTO | Usar esta skill para Expo/React Native | Detecte e redirecione antes da implementação |
Veja Também
- Skill
clerkpara roteamento Clerk de nível superior - Skill
clerk-setuppara configuração de início rápido entre frameworks https://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart