Clerk Android (nativ)
Diese Fähigkeit implementiert Clerk in nativen Android-Projekten durch Befolgung der aktuellen clerk-android SDK und Dokumentationsmuster.
Aktivierungsregeln
Aktiviere diese Fähigkeit, wenn eine der folgenden Bedingungen zutrifft:
- Der Benutzer fragt explizit nach Android, Kotlin, Jetpack Compose oder nativer mobiler Clerk-Implementierung auf Android.
- Das Projekt scheint eine native Android-App zu sein (z. B.
build.gradle(.kts)mit Android-Plugins,AndroidManifest.xml,app/src/main/java, Compose-UI-Dateien).
Aktiviere diese Fähigkeit nicht, wenn eine der folgenden Bedingungen zutrifft:
- Das Projekt ist Expo.
- Das Projekt ist React Native.
Wenn Signale für Expo/React Native vorhanden sind, leite zur allgemeinen Setup-Fähigkeit weiter.
Was wird benötigt?
| Aufgabe | Referenz |
|---|---|
| Vorgefertigte AuthView / UserButton (am schnellsten) | references/prebuilt.md |
| Benutzerdefinierte API-gesteuerte Auth-Abläufe (volle Kontrolle) | references/custom.md |
Kurzanleitung
| Schritt | Aktion |
|---|---|
| 1 | Bestätige, dass der Projekttyp nativ Android und nicht Expo/React Native ist |
| 2 | Bestimme den Ablauf-Typ (prebuilt oder custom) und lade die passende Referenzdatei |
| 3 | Stelle sicher, dass ein echter Clerk-Publishable-Key existiert (oder frage den Entwickler) |
| 4 | Stelle sicher, dass die richtigen Clerk-Artefakte für den ausgewählten Ablauf installiert sind |
| 5 | Lies die offizielle Android-Kurzanleitung und überprüfe die erforderliche Einrichtung (Native API, min SDK/Java, Manifest, Initialisierung) |
| 6 | Überprüfe die clerk-android Quell-/Beispielmuster, die für den ausgewählten Ablauf relevant sind |
| 7 | Implementiere den Ablauf, indem du nur der Checkliste der ausgewählten Referenz folgst |
Entscheidungsbaum
Benutzer fragt nach Clerk in Android/Kotlin
|
+-- Expo/React Native Projekt erkannt?
| |
| +-- JA -> Diese Fähigkeit nicht verwenden
| |
| +-- NEIN -> Fortfahren
|
+-- Vorhandene Auth-UI erkannt?
| |
| +-- Vorgefertigte Ansichten erkannt -> Lade references/prebuilt.md
| |
| +-- Benutzerdefinierter Ablauf erkannt -> Lade references/custom.md
| |
| +-- Neue Implementierung -> Frage Entwickler nach prebuilt/custom, dann lade passende Referenz
|
+-- Stelle sicher, dass Publishable-Key und SDK-Initialisierungspfad vorhanden sind
|
+-- Stelle sicher, dass die richtigen Android-Artefakte installiert sind
|
+-- Überprüfe die Quickstart-Voraussetzungen im Projekt
|
+-- Implementiere unter Verwendung der ausgewählten Ablauf-Referenz
Ablauf-Referenzen
Nachdem der Ablauf-Typ bekannt ist, lade genau eine davon:
- Prebuilt-Ablauf: references/prebuilt.md
- Benutzerdefinierter Ablauf: references/custom.md
Vermische die beiden Referenzen nicht in einer einzigen Implementierung, es sei denn, der Entwickler fragt explizit nach einem Hybrid-Ansatz.
Interaktionsvertrag
Vor allen Implementierungsänderungen muss der Agent beides haben:
- Ablauf-Auswahl:
prebuiltodercustom - einen echten Clerk-Publishable-Key
Fehlt einer der Werte in der Benutzeranfrage/im Kontext:
- frage den Benutzer nach dem/den fehlenden Wert(en)
- pausiere und warte auf die Antwort
- bearbeite keine Dateien und installiere keine Abhängigkeiten
Überspringe die Frage nur, wenn der Benutzer den Wert bereits explizit in dieser Unterhaltung angegeben hat.
Quellgesteuerte Vorlagen
Hardcodiere keine Implementierungsbeispiele in dieser Fähigkeit. Überprüfe vor der Implementierung die aktuellen clerk-android Quellen/Dokumentationen für die installierte SDK-Version.
| Anwendungsfall | Quelle der Wahrheit |
|---|---|
SDK-Artefakte und Abhängigkeitsaufteilung (clerk-android-api vs clerk-android-ui) | clerk-android README und Android-Installationsdokumente |
| SDK-Initialisierung und Publishable-Key-Einbindung | Android-Kurzanleitung und source/api/.../Clerk.kt |
| Verhalten von vorgefertigter Auth und Profil | source/ui/.../AuthView.kt, source/ui/.../UserButton.kt und Prebuilt-Beispiel |
| Benutzerdefinierte Auth-Abläufe und Faktorbehandlung | source/ui/auth/*, source/api/auth/* und Custom-Flows-Beispiel |
| Funktions-/Feature-Gating basierend auf Instanzeinstellungen | Öffentliche Felder von Clerk (z. B. enabledFirstFactorAttributes, socialProviders, isGoogleOneTapEnabled, mfaIsEnabled) und Umgebungsmodell-Quelle |
| Erforderliche Android-Setup-Checkliste | Offizielle Android-Kurzanleitung (/docs/android/getting-started/quickstart) |
Ausführungshürden (Nicht überspringen)
- Keine Implementierungsänderungen vor den Voraussetzungen
- Bearbeite keine Projektdateien, bis der Ablauf-Typ bestätigt ist und ein gültiger Publishable-Key verfügbar ist.
- Fehlender Ablauf oder fehlender Key muss eine Frage auslösen
- Wenn die Ablauf-Auswahl fehlt, frage explizit: vorgefertigte Ansichten oder benutzerdefinierter Ablauf.
- Wenn der Publishable-Key fehlt/Platzhalter/ungültig ist, frage explizit nach einem echten Key.
- Fahre nicht fort, bis beide Antworten gegeben sind.
- Einbindungsmodus des Publishable-Keys ist obligatorisch
- Standardmäßig binde den vom Entwickler bereitgestellten Key direkt in
Clerk.initialize(...)ein. - Führe keine Geheimnisverwaltungsindirektion ein, es sei denn, dies wird explizit angefordert.
- Installationsrichtlinie für Artefakte ist obligatorisch
- Prebuilt-Ablauf: verwende
clerk-android-ui(enthält API). - Benutzerdefinierter Ablauf: verwende
clerk-android-api, es sei denn, Prebuilt-Komponenten werden explizit angefordert. - Wenn Clerk-Artefakte fehlen, füge die neueste stabile verfügbare Version hinzu.
- Einhaltung der Android-Kurzanleitung ist obligatorisch
- Überprüfe, ob die Native API für die Clerk-App aktiviert ist.
- Überprüfe, ob die Android-Anforderungen aus der Kurzanleitung im Projekt implementiert sind (minimale SDK- und Java-Zielversion, Manifest-Internetberechtigung, app-level Clerk-Initialisierung).
- Überprüfe, ob die App auf die SDK-Initialisierung wartet (
Clerk.isInitialized), bevor sie den Auth-bereiten Zustand annimmt.
- Fähigkeitsgesteuertes Verhalten ist obligatorisch
- Verwende den Clerk-Laufzeit-Funktions-/Einstellungszustand (z. B. aktivierte Faktoren/Sozialanbieter/MFA-Flags), um das Ablaufverhalten zu steuern.
- Hardcodiere keine Faktorannahmen, die mit der Dashboard-Konfiguration in Konflikt geraten könnten.
- Disziplin der Referenzdatei ist obligatorisch
- Sobald ein Ablauf ausgewählt ist, folge nur dieser Ablauf-Referenzdatei für die Implementierung und Überprüfung.
- Strukturparität des benutzerdefinierten Ablaufs ist obligatorisch
- Für den
custom-Ablauf behalte die mehrstufige Auth-Abfolge und faktor-spezifische Behandlung bei (kein einzelnes All-Felder-Formular standardmäßig). - Halte UI, Zustandsorchestrierung und Clerk-API-Integration in separaten Modulen.
- Präferenz für Prebuilt ist obligatorisch, wenn ausgewählt
- Für den
prebuilt-Ablauf erstelle keine Auth-Formulare mit benutzerdefinierten API-Aufrufen neu, es sei denn, dies wird explizit angefordert. - Verwende
AuthView/UserButtonals Standardbausteine.
Arbeitsablauf
- Erkenne nativ Android vs. Expo/React Native.
- Wenn der Ablauf-Typ nicht explizit angegeben wurde, frage den Benutzer nach
prebuiltodercustom. - Wenn der Publishable-Key nicht explizit angegeben wurde, frage den Benutzer danach.
- Warte auf beide Antworten, bevor du Dateien änderst.
- Lade die passende Ablauf-Referenzdatei.
- Stelle sicher, dass der
Clerk.initialize(...)Pfad und die Publishable-Key-Einbindung gültig sind. - Stelle sicher, dass Abhängigkeiten/Artefakte zum ausgewählten Ablauf passen.
- Überprüfe die Android-Kurzanleitungsanforderungen und wende fehlende Einstellungen im Projekt an.
- Implementiere unter Verwendung der ausgewählten Referenz-Checkliste.
- Überprüfe unter Verwendung der ausgewählten Referenz-Checkliste plus gemeinsamer Hürden.
Häufige Fallstricke
| Ebene | Problem | Vermeidung |
|---|---|---|
| KRITISCH | Fehlende Ablauf-Auswahl vor der Implementierung nicht erfragen | Frage nach prebuilt vs custom und warte vor Änderungen |
| KRITISCH | Fehlenden Publishable-Key vor der Implementierung nicht erfragen | Frage nach dem Key und warte vor Änderungen |
| KRITISCH | Implementierung beginnen, bevor der Ablauf-Typ bestätigt ist | Bestätige zuerst den Ablauf und lade die passende Referenz |
| KRITISCH | Android-Kurzanleitungs-Voraussetzungen überspringen | Überprüfe und wende die erforderliche Einrichtung aus der offiziellen Android-Kurzanleitung an |
| KRITISCH | Fehlender app-level Clerk.initialize(...) Aufruf | Initialisiere Clerk vom Application-Startpfad aus |
| HOCH | Falsches Artefakt für den gewählten Ablauf | Prebuilt: clerk-android-ui; benutzerdefiniert: clerk-android-api |
| HOCH | Auth-UI rendern, bevor die SDK-Initialisierung abgeschlossen ist | Steuere die UI mit dem Clerk.isInitialized Zustand |
| HOCH | Auth-Faktoren/Sozialanbieter hartcodieren | Steuere das Verhalten von Clerk-Laufzeit-Fähigkeitsfeldern |
| HOCH | Diese Fähigkeit für Expo/React Native verwenden | Erkenne und leite vor der Implementierung weiter |
Siehe auch
clerkFähigkeit für Clerk-Routing auf oberster Ebeneclerk-setupFähigkeit für frameworkübergreifende Kurzanleitungseinrichtunghttps://github.com/clerk/clerk-androidhttps://clerk.com/docs/android/getting-started/quickstart