Iniziare a utilizzare la verifica del numero di telefono Firebase su Android

In questa pagina viene descritto come iniziare a utilizzare Firebase Phone Number Verification in un'app per Android. Consulta la panoramica per una descrizione generale di questa funzionalità.

Seguendo i passaggi descritti in questa pagina, puoi iniziare rapidamente a implementare i flussi utente per Firebase PNV. A scopo di test, genererai un token di sola verifica che rimanda a un numero di telefono fittizio. Utilizzando questo token di test, puoi iniziare ad aggiungere Firebase PNV alla tua app senza bisogno di un account di fatturazione o di un dispositivo con una SIM reale.

Quando l'esperienza utente di Firebase PNV nella tua app ti soddisfa, puoi seguire alcuni passaggi aggiuntivi per mettere in produzione l'app.

Prima di iniziare

• Se non l'hai già fatto, aggiungi Firebase al tuo progetto Android.

• Assicurati che la tua app soddisfi i seguenti requisiti:

  • Il valore minSdk della tua app è 24 (Android 7.0) o superiore.
  • Il dispositivo o l'emulatore dispone di Google Play Services. Per gli emulatori, utilizza un'immagine di sistema che includa Google Play.
  • Per verificare i numeri di telefono reali in produzione, il dispositivo deve eseguire Android 9 (livello API 28) o versioni successive e utilizzare una SIM di un operatore supportato. La modalità di test, descritta in questa pagina, non richiede una SIM reale.

1. Aggiungi la libreria Firebase PNV alla tua app

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

Con la Firebase Android BoM, la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

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. Inizializza la libreria Firebase PNV in modalità di test

1. Nella console Firebase, vai a Sicurezza > Verifica telefonica > Impostazioni > scheda Test.

2. Fai clic su Genera token, seleziona un codice paese, quindi fai di nuovo clic su Genera token per creare e copiare il token.

3. Rendi il token disponibile per le build di debug della tua app senza impostarlo come hardcoded nel codice sorgente. Tratta il token come una credenziale e non includerlo nel controllo della versione. Ad esempio, aggiungila al file local.properties del tuo progetto, che non è sottoposto al controllo della versione:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Quindi esponilo come campo BuildConfig nel file build.gradle.kts del modulo (a livello di app). L'esempio seguente legge anche una variabile di ambiente FPNV_TEST_TOKEN, utile sui server CI che non hanno un file local.properties. Le build di release ricevono un valore vuoto:

   // 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. Nella tua app, attiva una sessione di test una volta per processo dell'app:

   Kotlin

   FirebasePhoneNumberVerification.getInstance() restituisce la stessa istanza per FirebaseApp predefinito ogni volta che lo chiami, quindi utilizzalo per tutte le chiamate Firebase PNV.

   Chiama enableTestSession() una sola volta per processo dell'app. Una seconda chiamata genera un FirebasePhoneNumberVerificationException con il codice di errore TEST_SESSION_ALREADY_ENABLED, quindi non chiamarlo da un Activity, che può essere ricreato (ad esempio, quando lo schermo ruota). Chiamalo invece dalla classe 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)
       }
   }
   

   Registra la classe nel file manifest dell'app:

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

I token di test hanno un TTL di 7 giorni. Trascorso questo periodo, dovrai generare un nuovo token per attivare le sessioni di test. Un token scaduto non causa un errore finché non chiami getVerifiedPhoneNumber(). I token di test funzionano su dispositivi fisici ed emulatori con Google Play Services, il che li rende ideali per la prototipazione della UX nella tua app. Puoi utilizzarli anche per i test in CI/CD se sostituisci il token almeno ogni 7 giorni.

I token dei numeri di telefono che la tua app riceve in modalità di test sono firmati come i token di produzione, ma includono l'attestazione "test_number": true. Assicurati che il tuo backend di produzione rifiuti i token con questa attestazione.

3. Consigliato: verifica il supporto di Firebase PNV

Per aiutarti a determinare quando mostrare la UI di inserimento del numero o la UI esplicativa, all'avvio dell'app è consigliabile verificare se il dispositivo e la relativa scheda SIM supportano Firebase PNV. Si tratta di un controllo preliminare che non richiede il consenso dell'utente. Puoi utilizzare il risultato di questo test per decidere se avviare il flusso Firebase PNV o utilizzare un metodo alternativo di verifica del numero di telefono, ad esempio tramite SMS.

Per verificare la compatibilità del dispositivo, chiama il metodo getVerificationSupportInfo(). Quando hai una sessione di test attiva, questo metodo restituisce sempre un elenco contenente una singola voce supportata per il token di test, senza contattare il backend Firebase PNV. Ciò significa che non puoi esercitare il fallback per i dispositivi non supportati in modalità di test. In un secondo momento, dopo aver messo in produzione l'app, questo metodo restituirà un risultato per ogni SIM nel dispositivo.

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. Avvia il flusso di verifica

Per avviare il flusso Firebase PNV, chiama il metodo getVerifiedPhoneNumber(). Passa un Activity, perché il metodo mostra la schermata per il consenso. Un Context che non è un Activity, ad esempio il contesto Application, non va a buon fine con il codice di errore 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.
    }

Il metodo getVerifiedPhoneNumber() esegue l'intero flusso di verifica del numero di telefono, tra cui:

• Utilizzo di Gestore delle credenziali di Android per acquisire il consenso dell'utente alla condivisione del proprio numero di telefono.
• Effettua la richiesta al backend Firebase PNV.
• Restituzione di un token contenente il numero di telefono verificato per il dispositivo (in un'app di produzione, questo è il momento in cui avviene la fatturazione).

5. Gestisci gli errori

Quando una chiamata Firebase PNV non va a buon fine, l'eccezione è un FirebasePhoneNumberVerificationException. Utilizza il relativo errorCode per decidere cosa fare dopo, ad esempio per tornare alla verifica via SMS quando l'utente nega il consenso. Per ogni codice di errore, quando si verifica e il comportamento consigliato, consulta Gestisci gli errori di Firebase PNV su Android.

Passaggi successivi

• In questa pagina viene descritto come eseguire l'integrazione con Firebase PNV utilizzando l'API unificata a chiamata singola. La chiamata di un singolo metodo gestisce l'intero flusso utente di Firebase PNV, dall'ottenimento del consenso dell'utente all'esecuzione delle chiamate di rete necessarie al backend di Firebase PNV. Utilizzando questo metodo, riduci i passaggi di integrazione a una singola chiamata al metodo.

  Questa API è consigliata per la maggior parte degli sviluppatori. Tuttavia, se hai requisiti specifici non soddisfatti dalla libreria, consulta la pagina Personalizza il flusso Firebase Phone Number Verification per informazioni sull'implementazione di un flusso personalizzato.

• Se utilizzi il numero di telefono verificato al di fuori del client dell'app, devi passare il token anziché il numero di telefono stesso, in modo da poterne verificare l'integrità quando lo utilizzi. Consulta Verifica dei token Firebase PNV.

• Per consentire agli utenti di accedere a Firebase Authentication con il loro numero di telefono verificato, consulta Esegui l'autenticazione con Firebase utilizzando Firebase Phone Number Verification.

• Per una procedura dettagliata che crea un'app di esempio completa, prova il codelab Firebase Phone Number Verification.

• Dopo aver implementato e testato il flusso Firebase PNV e l'integrazione del backend della tua app, puoi metterla in produzione per iniziare a ricevere numeri di telefono verificati reali. Consulta Esegui l'upgrade alla modalità di produzione.

• Per l'API completa, consulta il riferimento API Firebase PNV.