Premiers pas avec la validation du numéro de téléphone Firebase sur Android

Cette page explique comment utiliser Firebase Phone Number Verification dans une application Android. Consultez la présentation pour obtenir une description générale de cette fonctionnalité.

En suivant les étapes de cette page, vous pouvez rapidement commencer à implémenter les parcours utilisateur pour Firebase PNV. À des fins de test, vous allez générer un jeton de test uniquement qui correspond à un faux numéro de téléphone. Ce jeton de test vous permet d'ajouter Firebase PNV à votre application sans avoir besoin d'un compte de facturation ni d'un appareil équipé d'une vraie carte SIM.

Une fois que vous êtes satisfait de l'expérience utilisateur Firebase PNV dans votre application, vous pouvez suivre quelques étapes supplémentaires pour la mettre en production.

Avant de commencer

• Ajoutez Firebase à votre projet Android si vous ne l'avez pas déjà fait.

• Assurez-vous que votre application répond aux exigences suivantes :

  • Le minSdk de votre application est défini sur 24 (Android 7.0) ou une version ultérieure.
  • L'appareil ou l'émulateur dispose des services Google Play. Pour les émulateurs, utilisez une image système incluant Google Play.
  • Pour valider de vrais numéros de téléphone en production, l'appareil doit exécuter Android 9 (niveau d'API 28) ou version ultérieure, et utiliser une carte SIM d'un opérateur compatible. Le mode test, décrit sur cette page, ne nécessite pas de vraie carte SIM.

1. Ajouter la bibliothèque Firebase PNV à votre application

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

Avec la Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques 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. Initialiser la bibliothèque Firebase PNV en mode test

1. Dans la console Firebase, accédez à Sécurité > Validation du numéro de téléphone > Paramètres > onglet Tests.

2. Cliquez sur Générer un jeton, sélectionnez un code pays, puis cliquez à nouveau sur Générer un jeton pour créer et copier votre jeton.

3. Rendez le jeton disponible pour les versions de débogage de votre application sans le coder en dur dans votre code source. Traitez le jeton comme un identifiant et ne l'incluez pas dans le contrôle des versions. Par exemple, ajoutez-la au fichier local.properties de votre projet, qui n'est pas enregistré dans le contrôle des versions :

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Ensuite, exposez-la en tant que champ BuildConfig dans le fichier build.gradle.kts de votre module (au niveau de l'application). L'exemple suivant lit également une variable d'environnement FPNV_TEST_TOKEN, ce qui est utile sur les serveurs d'intégration continue qui ne disposent pas d'un fichier local.properties. Les builds de release obtiennent une valeur vide :

   // 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. Dans votre application, activez une session de test une fois par processus d'application :

   Kotlin

   FirebasePhoneNumberVerification.getInstance() renvoie la même instance pour le FirebaseApp par défaut chaque fois que vous l'appelez. Utilisez-le donc pour tous les appels Firebase PNV.

   N'appelez enableTestSession() qu'une seule fois par processus d'application. Un deuxième appel génère une exception FirebasePhoneNumberVerificationException avec le code d'erreur TEST_SESSION_ALREADY_ENABLED. Ne l'appelez donc pas à partir d'une Activity, qui peut être recréée (par exemple, lorsque l'écran pivote). Appelez-la plutôt depuis votre 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)
       }
   }
   

   Enregistrez la classe dans le fichier manifeste de votre application :

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

Les jetons de test ont une valeur TTL de sept jours. Passé ce délai, vous devrez générer un nouveau jeton pour activer les sessions de test. Un jeton expiré ne génère pas d'erreur tant que vous n'appelez pas getVerifiedPhoneNumber(). Les jetons de test fonctionnent sur les appareils physiques et les émulateurs dotés des services Google Play. Ils sont donc parfaits pour prototyper l'expérience utilisateur dans votre application. Vous pouvez également les utiliser pour les tests dans l'intégration/le déploiement continus si vous remplacez le jeton au moins tous les sept jours.

Les jetons de numéro de téléphone que votre application obtient en mode test sont signés comme des jetons de production, mais ils incluent la revendication "test_number": true. Assurez-vous que votre backend de production rejette les jetons comportant cette revendication.

3. Recommandé : Vérifiez si votre appareil est compatible avec Firebase PNV

Pour vous aider à déterminer quand afficher l'UI de saisie du numéro ou l'UI explicative, nous vous recommandons de vérifier au lancement de l'application si l'appareil et sa carte SIM sont compatibles avec Firebase PNV. Il s'agit d'une vérification préalable qui ne nécessite pas le consentement utilisateur. Vous pouvez utiliser le résultat de ce test pour décider de lancer le flux Firebase PNV ou d'utiliser une autre méthode de vérification du numéro de téléphone, comme les SMS.

Pour vérifier la compatibilité de l'appareil, appelez la méthode getVerificationSupportInfo(). Lorsqu'une session de test est active, cette méthode renvoie toujours une liste contenant une seule entrée compatible pour le jeton de test, sans contacter le backend Firebase PNV. Cela signifie que vous ne pouvez pas tester votre solution de remplacement pour les appareils non compatibles en mode test. Plus tard, une fois que vous aurez mis votre application en production, cette méthode renverra un résultat pour chaque carte SIM de l'appareil.

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. Lancer le processus de validation

Pour lancer le flux Firebase PNV, appelez la méthode getVerifiedPhoneNumber(). Transmettez un Activity, car la méthode affiche l'écran de consentement. Un Context qui n'est pas un Activity, tel que votre contexte Application, échoue avec le code d'erreur 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.
    }

La méthode getVerifiedPhoneNumber() exécute l'intégralité du flux de validation du numéro de téléphone, y compris :

• Utiliser Android Credential Manager pour obtenir le consentement de l'utilisateur à partager son numéro de téléphone
• Envoi de la requête au backend Firebase PNV…
• Renvoi d'un jeton contenant le numéro de téléphone validé pour l'appareil (dans une application de production, c'est à ce moment que la facturation a lieu).

5. Gérer les erreurs

En cas d'échec d'un appel Firebase PNV, l'exception est un FirebasePhoneNumberVerificationException. Utilisez son errorCode pour décider de la marche à suivre, par exemple pour revenir à la validation par SMS lorsque l'utilisateur refuse de donner son consentement. Consultez Gérer les erreurs Firebase PNV sur Android pour connaître chaque code d'erreur, le moment où il se produit et l'action recommandée.

Étapes suivantes

• Cette page explique comment intégrer Firebase PNV à l'aide de l'API unifiée à appel unique. L'appel d'une seule méthode gère l'intégralité du parcours utilisateur Firebase PNV, de l'obtention du consentement utilisateur à l'envoi des appels réseau nécessaires au backend Firebase PNV. En utilisant cette méthode, vous réduisez les étapes d'intégration à un seul appel de méthode.

  Cette API est recommandée pour la plupart des développeurs. Toutefois, si vous avez des exigences spécifiques auxquelles la bibliothèque ne répond pas, consultez la page Personnaliser le flux Firebase Phone Number Verification pour savoir comment implémenter un flux personnalisé.

• Si vous utilisez le numéro de téléphone validé en dehors du client de l'application, vous devez transmettre le jeton au lieu du numéro de téléphone lui-même afin de pouvoir vérifier son intégrité lorsque vous l'utilisez. Consultez Valider les jetons Firebase PNV.

• Pour connecter des utilisateurs à Firebase Authentication avec leur numéro de téléphone validé, consultez S'authentifier auprès de Firebase à l'aide de Firebase Phone Number Verification.

• Pour obtenir un guide par étapes permettant de créer une application exemple complète, suivez l'atelier de programmation Firebase Phone Number Verification.

• Une fois que vous avez implémenté et testé le flux Firebase PNV et l'intégration du backend de votre application, vous pouvez la mettre en production pour commencer à obtenir de vrais numéros de téléphone validés. Consultez Passer en mode Production.

• Pour l'API complète, consultez la documentation de référence de l'API Firebase PNV.