Pierwsze kroki z weryfikacją numeru telefonu w Firebase na Androidzie

Na tej stronie dowiesz się, jak zacząć korzystać z Firebase Phone Number Verification w aplikacji na Androida. Ogólny opis tej funkcji znajdziesz w omówieniu.

Wykonując czynności opisane na tej stronie, możesz szybko rozpocząć wdrażanie wzorców przeglądania w usłudze Firebase PNV. Do celów testowych wygenerujesz token tylko do testowania, który będzie odpowiadał fałszywemu numerowi telefonu. Za pomocą tego tokena testowego możesz zacząć dodawać Firebase PNV do aplikacji bez konieczności posiadania konta rozliczeniowego lub urządzenia z prawdziwą kartą SIM.

Gdy uznasz, że interfejs użytkownika Firebase PNV w aplikacji jest zadowalający, możesz wykonać kilka dodatkowych czynności, aby przygotować aplikację do środowiska produkcyjnego.

Zanim zaczniesz

• Dodaj Firebase do projektu aplikacji na Androida, jeśli nie korzystasz w nim jeszcze z tej usługi.

• Upewnij się, że aplikacja spełnia te wymagania:

  • Wartość minSdk aplikacji to 24 (Android 7.0) lub więcej.
  • Urządzenie lub emulator ma Usługi Google Play. W przypadku emulatorów użyj obrazu systemu, który zawiera Google Play.
  • Aby zweryfikować prawdziwe numery telefonów w środowisku produkcyjnym, urządzenie musi mieć Androida 9 (poziom interfejsu API 28) lub nowszego i korzystać z karty SIM obsługiwanego operatora. Tryb testowy opisany na tej stronie nie wymaga prawdziwej karty SIM.

1. Dodawanie biblioteki Firebase PNV do aplikacji

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")
}

Gdy korzystasz z Firebase Android BoM, aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

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. Zainicjuj bibliotekę Firebase PNV w trybie testowym

1. W konsoli Firebase otwórz kartę Zabezpieczenia > Weryfikacja telefoniczna > Ustawienia > Testowanie.

2. Kliknij Wygeneruj token, wybierz kod kraju, a następnie ponownie kliknij Wygeneruj token, aby utworzyć i skopiować token.

3. Udostępnij token kompilacjom do debugowania aplikacji bez kodowania go na stałe w kodzie źródłowym. Traktuj token jak dane logowania i nie umieszczaj go w systemie kontroli wersji. Możesz na przykład dodać go do pliku local.properties projektu, który nie jest sprawdzany w systemie kontroli wersji:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Następnie udostępnij go jako pole BuildConfig w pliku build.gradle.kts modułu (na poziomie aplikacji). W poniższym przykładzie odczytywana jest też zmienna środowiskowa FPNV_TEST_TOKEN, co jest przydatne na serwerach CI, które nie mają pliku local.properties. Kompilacje do publikacji otrzymują pustą wartość:

   // 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. W aplikacji włącz sesję testową raz na proces aplikacji:

   Kotlin

   FirebasePhoneNumberVerification.getInstance() zwraca tę samą instancję domyślnego FirebaseApp za każdym razem, gdy ją wywołujesz, więc używaj jej we wszystkich wywołaniach Firebase PNV.

   Wywołaj enableTestSession() tylko raz na proces aplikacji. Drugie wywołanie powoduje zgłoszenie błędu FirebasePhoneNumberVerificationException z kodem błędu TEST_SESSION_ALREADY_ENABLED, więc nie wywołuj go z Activity, który można odtworzyć (np. podczas obracania ekranu). Zamiast tego wywołaj ją z klasy Application:

   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)
       }
   }
   

   Zarejestruj klasę w manifeście aplikacji:

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

Tokeny testowe mają 7-dniowy czas życia. Po tym okresie musisz wygenerować nowy token, aby umożliwić sesje testowe. Wygasły token nie powoduje błędu, dopóki nie wywołasz funkcji getVerifiedPhoneNumber(). Tokeny testowe działają na urządzeniach fizycznych i emulatorach z usługami Google Play, dzięki czemu idealnie nadają się do prototypowania UX w aplikacji. Możesz ich też używać do testowania w CI/CD, jeśli wymieniasz token co najmniej co 7 dni.

Tokeny numerów telefonów, które aplikacja otrzymuje w trybie testowym, są podpisywane tak samo jak tokeny produkcyjne, ale zawierają deklarację "test_number": true. Upewnij się, że Twój produkcyjny backend odrzuca tokeny z tym oświadczeniem.

3. Zalecane: sprawdź, czy Firebase PNV jest obsługiwany

Aby określić, kiedy wyświetlać interfejs wprowadzania numeru lub interfejs z wyjaśnieniem, zalecamy sprawdzenie przy uruchamianiu aplikacji, czy urządzenie i jego karta SIM obsługują Firebase PNV. Jest to wstępna weryfikacja, która nie wymaga zgody użytkownika. Na podstawie wyniku tego testu możesz zdecydować, czy chcesz zainicjować proces Firebase PNV, czy użyć alternatywnej metody weryfikacji numeru telefonu, np. SMS-a.

Aby sprawdzić zgodność urządzenia, wywołaj metodę getVerificationSupportInfo(). Gdy sesja testowa jest aktywna, ta metoda zawsze zwraca listę zawierającą pojedynczy obsługiwany wpis dla tokena testowego, bez kontaktu z backendem Firebase PNV. Oznacza to, że w trybie testowym nie możesz sprawdzić działania kreacji zastępczej na nieobsługiwanych urządzeniach. Później, gdy aplikacja będzie już w wersji produkcyjnej, ta metoda będzie zwracać wynik dla każdej karty SIM w urządzeniu.

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. Rozpoczynanie procesu weryfikacji

Aby rozpocząć proces Firebase PNV, wywołaj metodę getVerifiedPhoneNumber(). Przekaż obiekt Activity, ponieważ metoda wyświetla ekran zgody. Context, który nie jest Activity, np. kontekst Application, kończy się niepowodzeniem z kodem błędu ACTIVITY_CONTEXT_REQUIRED.

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.
    }

Metoda getVerifiedPhoneNumber() przeprowadza cały proces weryfikacji numeru telefonu, w tym:

• używanie Menedżera danych logowania na Androidzie do uzyskiwania zgody użytkownika na udostępnianie jego numeru telefonu;
• Wysyłam żądanie do backendu Firebase PNV.
• Zwrócenie tokena zawierającego zweryfikowany numer telefonu urządzenia (w aplikacji produkcyjnej jest to moment, w którym następuje rozliczenie).

5. Obsługuj błędy

Gdy wywołanie Firebase PNV się nie powiedzie, wyjątek to FirebasePhoneNumberVerificationException. Użyj errorCode, aby zdecydować, co zrobić dalej, na przykład wrócić do weryfikacji SMS-em, gdy użytkownik nie wyrazi zgody. W artykule Obsługa błędów Firebase PNV na Androidzie znajdziesz wszystkie kody błędów, informacje o tym, kiedy występują, oraz zalecane działania.

Dalsze kroki

• Na tej stronie dowiesz się, jak przeprowadzić integrację z Firebase PNV za pomocą ujednoliconego interfejsu API z pojedynczym wywołaniem. Wywołanie jednej metody obsługuje cały wzorzec przeglądania użytkownika Firebase PNV, od uzyskania zgody użytkownika po wykonanie niezbędnych wywołań sieciowych do backendu Firebase PNV. Dzięki tej metodzie ograniczysz kroki integracji do jednego wywołania metody.

  Ten interfejs API jest zalecany dla większości deweloperów. Jeśli jednak masz określone wymagania, których biblioteka nie spełnia, zapoznaj się ze stroną Dostosowywanie procesu Firebase Phone Number Verification, aby dowiedzieć się, jak wdrożyć proces niestandardowy.

• Jeśli używasz zweryfikowanego numeru telefonu poza klientem aplikacji, zamiast samego numeru telefonu przekazuj token, aby móc zweryfikować jego integralność podczas używania. Zobacz Weryfikowanie tokenów Firebase PNV.

• Aby logować użytkowników w aplikacji Firebase Authentication za pomocą ich zweryfikowanego numeru telefonu, zapoznaj się z artykułem Uwierzytelnianie w Firebase za pomocą Firebase Phone Number Verification.

• Szczegółowe instrukcje tworzenia kompletnej przykładowej aplikacji znajdziesz w ćwiczeniach z programowania Firebase Phone Number Verification.

• Po wdrożeniu i przetestowaniu procesu Firebase PNV oraz integracji backendu aplikacji możesz wprowadzić ją do środowiska produkcyjnego, aby zacząć otrzymywać prawdziwe, zweryfikowane numery telefonów. Zobacz Przechodzenie na tryb produkcyjny.

• Pełny interfejs API znajdziesz w dokumentacji interfejsu API Firebase PNV.