Clerk Android (Natif)
Cette compétence implémente Clerk dans des projets Android natifs en suivant les modèles actuels de la SDK clerk-android et de la documentation.
Règles d'activation
Activez cette compétence si l'une des conditions suivantes est vraie :
- L'utilisateur demande explicitement une implémentation Clerk pour Android, Kotlin, Jetpack Compose ou mobile natif sur Android.
- Le projet semble être un projet Android natif (par exemple
build.gradle(.kts)avec des plugins Android,AndroidManifest.xml,app/src/main/java, fichiers Compose UI).
N'activez PAS cette compétence si l'une des conditions suivantes est vraie :
- Le projet est Expo.
- Le projet est React Native.
Si des signaux Expo/React Native sont présents, redirigez vers la compétence de configuration générale.
De quoi avez-vous besoin ?
| Tâche | Référence |
|---|---|
| AuthView / UserButton préconstruit (le plus rapide) | references/prebuilt.md |
| Flux d'authentification personnalisés via API (contrôle total) | references/custom.md |
Démarrage rapide
| Étape | Action |
|---|---|
| 1 | Confirmer que le type de projet est Android natif et non Expo/React Native |
| 2 | Déterminer le type de flux (prebuilt ou custom) et charger le fichier de référence correspondant |
| 3 | S'assurer qu'une véritable clé publishable Clerk existe (ou demander au développeur) |
| 4 | S'assurer que les artefacts Clerk corrects sont installés pour le flux sélectionné |
| 5 | Lire le quickstart officiel Android et vérifier la configuration requise (Native API, SDK/Java minimum, manifeste, initialisation) |
| 6 | Inspecter les sources/exemples de clerk-android pertinents pour le flux sélectionné |
| 7 | Implémenter le flux en suivant uniquement la checklist du fichier de référence sélectionné |
Arbre de décision
L'utilisateur demande Clerk pour Android/Kotlin
|
+-- Projet Expo/React Native détecté ?
| |
| +-- OUI -> Ne pas utiliser cette compétence
| |
| +-- NON -> Continuer
|
+-- Interface d'authentification existante détectée ?
| |
| +-- Vues préconstruites détectées -> Charger references/prebuilt.md
| |
| +-- Flux personnalisé détecté -> Charger references/custom.md
| |
| +-- Nouvelle implémentation -> Demander au développeur prebuilt/custom, puis charger la référence correspondante
|
+-- S'assurer que la clé publishable et le chemin d'initialisation SDK sont présents
|
+-- S'assurer que les artefacts Android corrects sont installés
|
+-- Vérifier les prérequis du quickstart dans le projet
|
+-- Implémenter à l'aide de la référence du flux sélectionné
Références de flux
Une fois le type de flux connu, chargez exactement un fichier :
- Flux préconstruit : references/prebuilt.md
- Flux personnalisé : references/custom.md
Ne mélangez pas les deux références dans une seule implémentation sauf si le développeur demande explicitement une approche hybride.
Contrat d'interaction
Avant toute modification d'implémentation, l'agent doit disposer des deux éléments suivants :
- le choix du flux :
prebuiltoucustom - une véritable clé publishable Clerk
Si l'une de ces valeurs manque dans la demande/le contexte de l'utilisateur :
- demandez à l'utilisateur la ou les valeurs manquantes
- faites une pause et attendez la réponse
- ne modifiez pas encore les fichiers ni n'installez les dépendances
Ne sautez cette question que si l'utilisateur a déjà explicitement fourni la valeur dans cette conversation.
Modèles basés sur les sources
Ne codez pas en dur des exemples d'implémentation dans cette compétence. Inspectez les sources/documentations actuelles de clerk-android pour la version SDK installée avant d'implémenter.
| Cas d'utilisation | Source de vérité |
|---|---|
Artefacts SDK et répartition des dépendances (clerk-android-api vs clerk-android-ui) | README de clerk-android et documentation d'installation Android |
| Initialisation SDK et câblage de la clé publishable | Quickstart Android et source/api/.../Clerk.kt |
| Comportement préconstruit de l'authentification et du profil | source/ui/.../AuthView.kt, source/ui/.../UserButton.kt et échantillon préconstruit |
| Séquençage personnalisé de l'authentification et gestion des facteurs | source/ui/auth/*, source/api/auth/* et échantillon de flux personnalisé |
| Contrôle des fonctionnalités basé sur les paramètres de l'instance | Champs publics de Clerk (par exemple enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) et modèle d'environnement source |
| Checklist de configuration requise Android | Quickstart officiel Android (/docs/android/getting-started/quickstart) |
Points de contrôle obligatoires (À ne pas sauter)
-
Aucune modification d'implémentation avant les prérequis
- Ne modifiez pas les fichiers du projet tant que le type de flux n'est pas confirmé et qu'une clé publishable valide n'est pas disponible.
-
Manque de flux ou de clé doit déclencher une question
- Si le choix du flux est manquant, demandez explicitement : vues préconstruites ou flux personnalisé.
- Si la clé publishable est manquante/remplacer/invalide, demandez explicitement une vraie clé.
- Ne continuez pas avant d'avoir reçu les deux réponses.
-
Le mode de câblage de la clé publishable est obligatoire
- Par défaut, câblez la clé fournie par le développeur directement dans
Clerk.initialize(...). - N'introduisez pas d'indirection de gestion des secrets sauf demande explicite.
- Par défaut, câblez la clé fournie par le développeur directement dans
-
La politique d'installation des artefacts est obligatoire
- Flux préconstruit : utilisez
clerk-android-ui(inclut l'API). - Flux personnalisé : utilisez
clerk-android-apisauf si les composants préconstruits sont explicitement demandés. - Si les artefacts Clerk sont manquants, ajoutez la dernière version stable disponible.
- Flux préconstruit : utilisez
-
La conformité au quickstart Android est obligatoire
- Vérifiez que l'API Native est activée pour l'application Clerk.
- Vérifiez que les exigences Android du quickstart sont implémentées dans le projet (SDK minimum et cible Java, permission internet dans le manifeste, initialisation Clerk au niveau de l'application).
- Vérifiez que l'application attend l'initialisation SDK (
Clerk.isInitialized) avant de supposer un état prêt pour l'authentification.
-
Le comportement piloté par les capacités est obligatoire
- Utilisez les capacités/paramètres d'exécution de Clerk (par exemple facteurs activés/fournisseurs sociaux/drapeaux MFA) pour contrôler le comportement du flux.
- Ne codez pas en dur des hypothèses de facteurs qui pourraient entrer en conflit avec la configuration du tableau de bord.
-
La discipline du fichier de référence est obligatoire
- Une fois le flux sélectionné, suivez uniquement ce fichier de référence pour l'implémentation et la vérification.
-
La parité structurelle du flux personnalisé est obligatoire
- Pour le flux
custom, conservez la progression d'authentification multi-étapes et la gestion spécifique aux facteurs (pas de formulaire unique tous-facteurs par défaut). - Gardez l'UI, l'orchestration d'état et l'intégration à l'API Clerk dans des modules séparés.
- Pour le flux
-
La préférence pour le flux préconstruit est obligatoire lorsqu'il est sélectionné
- Pour le flux
prebuilt, ne reconstruisez pas les formulaires d'authentification avec des appels API personnalisés sauf demande explicite. - Utilisez
AuthView/UserButtoncomme blocs de construction par défaut.
- Pour le flux
Flux de travail
- Détecter Android natif vs Expo/React Native.
- Si le type de flux n'est pas explicitement fourni, demandez à l'utilisateur
prebuiltoucustom. - Si la clé publishable n'est pas explicitement fournie, demandez-la à l'utilisateur.
- Attendez les deux réponses avant de modifier les fichiers.
- Chargez le fichier de référence correspondant au flux.
- Assurez-vous que le chemin
Clerk.initialize(...)et le câblage de la clé publishable sont valides. - Assurez-vous que les dépendances/artefacts correspondent au flux sélectionné.
- Passez en revue les exigences du quickstart Android et appliquez la configuration manquante dans le projet.
- Implémentez à l'aide de la checklist de la référence sélectionnée.
- Vérifiez à l'aide de la checklist de la référence sélectionnée et des points de contrôle partagés.
Pièges courants
| Niveau | Problème | Prévention |
|---|---|---|
| CRITIQUE | Ne pas demander le choix du flux manquant avant l'implémentation | Demandez prebuilt vs custom et attendez avant les modifications |
| CRITIQUE | Ne pas demander la clé publishable manquante avant l'implémentation | Demandez la clé et attendez avant les modifications |
| CRITIQUE | Commencer l'implémentation avant que le type de flux soit confirmé | Confirmez d'abord le flux et chargez la référence correspondante |
| CRITIQUE | Sauter les prérequis du quickstart Android | Vérifiez et appliquez la configuration requise depuis le quickstart officiel Android |
| CRITIQUE | Appel Clerk.initialize(...) manquant au niveau de l'application | Initialisez Clerk depuis le chemin de démarrage de l'Application |
| ÉLEVÉ | Mauvais artefact pour le flux choisi | Préconstruit : clerk-android-ui ; personnalisé : clerk-android-api |
| ÉLEVÉ | Afficher l'UI d'authentification avant la fin de l'initialisation SDK | Bloquez l'UI avec l'état Clerk.isInitialized |
| ÉLEVÉ | Coder en dur les facteurs d'authentification/fournisseurs sociaux | Pilotez le comportement depuis les champs de capacité d'exécution de Clerk |
| ÉLEVÉ | Utiliser cette compétence pour Expo/React Native | Détectez et redirigez avant l'implémentation |
Voir aussi
- Compétence
clerkpour le routage Clerk de haut niveau - Compétence
clerk-setuppour la configuration de démarrage rapide cross-framework https://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart