Erste Schritte mit der Firebase-Bestätigung der Telefonnummer unter Android

Auf dieser Seite wird beschrieben, wie Sie Firebase Phone Number Verification in einer Android-App verwenden. Eine allgemeine Beschreibung dieser Funktion finden Sie in der Übersicht.

Wenn du die Schritte auf dieser Seite ausführst, kannst du die Nutzerflüsse für Firebase PNV schnell implementieren. Zu Testzwecken generieren Sie ein Testtoken, das zu einer gefälschten Telefonnummer aufgelöst wird. Mit diesem Testtoken können Sie Firebase PNV in Ihre App einbinden, ohne ein Rechnungskonto oder ein Gerät mit einer echten SIM-Karte zu benötigen.

Wenn Sie mit der Firebase PNV-Nutzererfahrung in Ihrer App zufrieden sind, können Sie einige zusätzliche Schritte ausführen, um Ihre App für die Produktion vorzubereiten.

Hinweis

• Fügen Sie Ihrem Android-Projekt Firebase hinzu, falls noch nicht geschehen.

• Ihre App muss die folgenden Anforderungen erfüllen:

  • Die minSdk Ihrer App ist 24 (Android 7.0) oder höher.
  • Auf dem Gerät oder Emulator sind die Google Play-Dienste installiert. Verwenden Sie für Emulatoren ein System-Image, das Google Play enthält.
  • Wenn Sie echte Telefonnummern in der Produktion bestätigen möchten, muss auf dem Gerät Android 9 (API-Level 28) oder höher installiert sein und es muss eine SIM-Karte von einem unterstützten Mobilfunkanbieter verwendet werden. Für den auf dieser Seite beschriebenen Testmodus ist keine echte SIM-Karte erforderlich.

1. Firebase PNV-Bibliothek zur App hinzufügen

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.1.0"))

    // Add the dependencies for the Firebase Phone Number Verification libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-pnv")
}

Mit der Firebase Android BoM haben Sie immer eine kompatible Version der Firebase Android-Bibliotheken in Ihrer App.

dependencies {
    // Add the dependencies for the Firebase Phone Number Verification libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-pnv:17.0.0")
}

2. Firebase PNV-Bibliothek im Testmodus initialisieren

1. Rufen Sie in der Firebase-Konsole den Tab Sicherheit > Bestätigung der Telefonnummer > Einstellungen > Test auf.

2. Klicken Sie auf Token generieren, wählen Sie einen Ländercode aus und klicken Sie dann noch einmal auf Token generieren, um das Token zu erstellen und zu kopieren.

3. Stellen Sie das Token für Debug-Builds Ihrer App zur Verfügung, ohne es in Ihrem Quellcode hartcodieren zu müssen. Behandeln Sie das Token wie einen Berechtigungsnachweis und schließen Sie es von der Versionsverwaltung aus. Fügen Sie ihn beispielsweise der Datei local.properties Ihres Projekts hinzu, die nicht in die Versionsverwaltung eingecheckt wird:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Stellen Sie sie dann als BuildConfig-Feld in der build.gradle.kts-Datei Ihres Moduls (auf App-Ebene) bereit. Im folgenden Beispiel wird auch eine FPNV_TEST_TOKEN-Umgebungsvariable gelesen, was auf CI-Servern ohne local.properties-Datei nützlich ist. Release-Builds erhalten einen leeren Wert:

   // At the top of the file:
   import java.util.Properties
   
   val localProperties = Properties().apply {
       rootProject.file("local.properties").takeIf { it.exists() }
           ?.inputStream()?.use { load(it) }
   }
   val fpnvTestToken = System.getenv("FPNV_TEST_TOKEN")?.takeIf { it.isNotEmpty() }
       ?: localProperties.getProperty("fpnv.testToken", "")
   
   android {
       buildFeatures {
           buildConfig = true
       }
       buildTypes {
           debug {
               buildConfigField("String", "FPNV_TEST_TOKEN", "\"$fpnvTestToken\"")
           }
           release {
               buildConfigField("String", "FPNV_TEST_TOKEN", "\"\"")
           }
       }
   }
   

4. Aktivieren Sie in Ihrer App einmal pro App-Prozess eine Testsitzung:

   Kotlin

   FirebasePhoneNumberVerification.getInstance() gibt bei jedem Aufruf dieselbe Instanz für die Standard-FirebaseApp zurück. Verwenden Sie sie daher für alle Firebase PNV-Aufrufe.

   Rufen Sie enableTestSession() nur einmal pro App-Prozess auf. Ein zweiter Aufruf löst eine FirebasePhoneNumberVerificationException mit dem Fehlercode TEST_SESSION_ALREADY_ENABLED aus. Rufen Sie die Methode daher nicht über eine Activity auf, die neu erstellt werden kann (z. B. wenn der Bildschirm gedreht wird). Rufen Sie sie stattdessen über die Klasse Application auf:

   import android.app.Application
   import android.util.Log
   import com.google.firebase.pnv.FirebasePhoneNumberVerification
   
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           if (!BuildConfig.DEBUG) return
           if (BuildConfig.FPNV_TEST_TOKEN.isEmpty()) {
               Log.w("MyApplication", "No Firebase PNV test token; test mode is off.")
               return
           }
           FirebasePhoneNumberVerification.getInstance()
               .enableTestSession(BuildConfig.FPNV_TEST_TOKEN)
       }
   }
   

   Registrieren Sie die Klasse in Ihrem App-Manifest:

   <application
       android:name=".MyApplication"
       ... >
   

Test-Tokens haben eine TTL von 7 Tagen. Nach diesem Zeitraum müssen Sie ein neues Token generieren, um Testsitzungen zu ermöglichen. Ein abgelaufenes Token verursacht erst dann einen Fehler, wenn Sie getVerifiedPhoneNumber() aufrufen. Test-Tokens funktionieren auf physischen Geräten und Emulatoren mit Google Play-Diensten. Sie eignen sich daher ideal für das Prototyping der UX in Ihrer App. Sie können sie auch für Tests in CI/CD verwenden, wenn Sie das Token mindestens alle 7 Tage ersetzen.

Telefonnummer-Tokens, die Ihre App im Testmodus erhält, werden wie Produktions-Tokens signiert, enthalten aber die Anforderung "test_number": true. Achten Sie darauf, dass Ihr Produktions-Backend Tokens mit dieser Anforderung ablehnt.

3. Empfohlen: Unterstützung für Firebase PNV prüfen

Damit du besser entscheiden kannst, wann die Benutzeroberfläche für die Nummerneingabe oder die Erläuterung angezeigt werden soll, solltest du beim Start der App prüfen, ob das Gerät und die SIM-Karte Firebase PNV unterstützen. Dies ist eine Vorabprüfung, für die keine Nutzereinwilligung erforderlich ist. Anhand des Ergebnisses dieses Tests können Sie entscheiden, ob Sie den Firebase PNV-Ablauf initiieren oder eine alternative Methode zur Bestätigung der Telefonnummer verwenden möchten, z. B. SMS.

Rufen Sie die Methode getVerificationSupportInfo() auf, um die Kompatibilität des Geräts zu prüfen. Solange eine Testsitzung aktiv ist, gibt diese Methode immer eine Liste mit einem einzelnen unterstützten Eintrag für das Testtoken zurück, ohne das Firebase PNV-Backend zu kontaktieren. Das bedeutet, dass du im Testmodus nicht auf den Fallback für nicht unterstützte Geräte zurückgreifen kannst. Nachdem Sie Ihre App in die Produktion überführt haben, gibt diese Methode ein Ergebnis für jede SIM-Karte im Gerät zurück.

val fpnv = FirebasePhoneNumberVerification.getInstance()

// Check all SIMs for support.
fpnv.getVerificationSupportInfo()
    .addOnSuccessListener { results ->
        if (results.any { it.isSupported() }) {
            // At least one SIM is supported; okay to call getVerifiedPhoneNumber
            // (see the next step).
        } else {
            // No SIMs are supported, so fall back to SMS verification.
        }
    }
    .addOnFailureListener { e ->
        // Handle error.
    }

4. Bestätigungsvorgang starten

Rufen Sie die Methode getVerifiedPhoneNumber() auf, um den Firebase PNV-Vorgang zu starten. Übergeben Sie ein Activity, da die Methode den Zustimmungsbildschirm anzeigt. Ein Context, der kein Activity ist, z. B. Ihr Application-Kontext, schlägt mit dem Fehlercode ACTIVITY_CONTEXT_REQUIRED fehl.

fpnv.getVerifiedPhoneNumber(this@MainActivity)
    .addOnSuccessListener { result ->
        // In test mode, this phone number will have a valid country code,
        // followed by all zeros.
        val phoneNumber = result.getPhoneNumber() // For display only.
        val token = result.getToken()

        // Verification successful. Send token to your backend, which reads
        // the verified phone number from it. (See Next steps.)
    }
    .addOnFailureListener { e ->
        // Handle failures, such as the user declining consent or a network
        // error.
    }

Die Methode getVerifiedPhoneNumber() führt den gesamten Ablauf zur Bestätigung der Telefonnummer aus, einschließlich:

• Verwendung des Android Credential Manager, um die Nutzereinwilligung zur Weitergabe seiner Telefonnummer einzuholen.
• Anfrage an das Firebase PNV-Backend stellen.
• Rückgabe eines Tokens mit der bestätigten Telefonnummer für das Gerät (in einer Produktions-App erfolgt hier die Abrechnung)

5. Fehler verarbeiten

Wenn ein Firebase PNV-Aufruf fehlschlägt, ist die Ausnahme ein FirebasePhoneNumberVerificationException. Anhand des errorCode-Werts können Sie entscheiden, was als Nächstes zu tun ist, z. B. auf die SMS-Bestätigung zurückgreifen, wenn der Nutzer die Einwilligung verweigert. Unter Firebase PNV-Fehler unter Android beheben finden Sie alle Fehlercodes, wann sie auftreten und die empfohlene Maßnahme.

Nächste Schritte

• Auf dieser Seite wird beschrieben, wie Sie Firebase PNV mithilfe der einheitlichen API mit einem einzelnen Aufruf einbinden. Durch den Aufruf einer einzelnen Methode wird der gesamte Firebase PNV-Nutzerablauf abgewickelt, von der Einholung der Nutzereinwilligung bis hin zu den erforderlichen Netzwerkaufrufen an das Firebase PNV-Backend. Mit dieser Methode reduzieren Sie die Integrationsschritte auf einen einzigen Methodenaufruf.

  Diese API wird für die meisten Entwickler empfohlen. Wenn Sie jedoch bestimmte Anforderungen haben, die von der Bibliothek nicht erfüllt werden, finden Sie auf der Seite Firebase Phone Number Verification-Ablauf anpassen Informationen zum Implementieren eines benutzerdefinierten Ablaufs.

• Wenn du die bestätigte Telefonnummer außerhalb des App-Clients verwendest, solltest du das Token anstelle der Telefonnummer selbst weitergeben, damit du die Integrität der Nummer bei der Verwendung überprüfen kannst. Weitere Informationen finden Sie unter Firebase PNV-Tokens prüfen.

• Informationen zum Anmelden von Nutzern bei Firebase Authentication mit ihrer bestätigten Telefonnummer finden Sie unter Mit Firebase über Firebase Phone Number Verification authentifizieren.

• Eine detaillierte Anleitung zum Erstellen einer vollständigen Beispiel-App finden Sie im Firebase Phone Number Verification-Codelab.

• Nachdem du den Firebase PNV-Ablauf und die Backend-Integration deiner App implementiert und getestet hast, kannst du deine App in die Produktion überführen, um echte bestätigte Telefonnummern zu erhalten. Weitere Informationen finden Sie unter Upgrade auf den Produktionsmodus.

• Die vollständige API finden Sie in der Firebase PNV API-Referenz.