אימות מספר טלפון ב-Firebase ב-Android

בדף הזה מוסבר איך להתחיל להשתמש ב-Firebase Phone Number Verification באפליקציה ל-Android. בסקירה הכללית מופיע תיאור כללי של התכונה הזו.

כדי להתחיל להטמיע במהירות את מסלולי המשתמשים ב-Firebase PNV, פועלים לפי השלבים שבדף הזה. למטרות בדיקה, תיצרו אסימון לבדיקה בלבד שמתייחס למספר טלפון מזויף. באמצעות הטוקן הזה לבדיקה, אתם יכולים להתחיל להוסיף את Firebase PNV לאפליקציה בלי צורך בחשבון לחיוב או במכשיר עם כרטיס SIM אמיתי.

אחרי שאתם מרוצים מחוויית המשתמש של Firebase PNV באפליקציה, אתם יכולים לבצע כמה שלבים נוספים כדי להעביר את האפליקציה לסביבת הייצור.

לפני שמתחילים

• אם עדיין לא עשיתם זאת, הוסיפו את Firebase לפרויקט Android.

• צריך לוודא שהאפליקציה עומדת בדרישות הבאות:

  • ה-minSdk של האפליקציה הוא 24 (Android 7.0) ומעלה.
  • במכשיר או באמולטור מותקנת אפליקציית Google Play Services. באמולטורים, צריך להשתמש בתמונת מערכת שכוללת את Google Play.
  • כדי לאמת מספרי טלפון אמיתיים בסביבת הייצור, המכשיר צריך לפעול עם Android מגרסה 9 (רמת API‏ 28) ומעלה, ולהשתמש בכרטיס SIM של ספק נתמך. במצב הבדיקה שמתואר בדף הזה, לא צריך כרטיס SIM אמיתי.

1. להוסיף את ספריית Firebase PNV לאפליקציה

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

כשמשתמשים ב-Firebase Android BoM, האפליקציה תמיד משתמשת בגרסאות תואמות של ספריות 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. מאתחלים את הספרייה Firebase PNV במצב בדיקה

1. במסוף Firebase, נכנסים לכרטיסייה אבטחה > אימות טלפוני > הגדרות > בדיקה.

2. לוחצים על Generate token (יצירת אסימון), בוחרים קוד מדינה ולוחצים שוב על Generate token (יצירת אסימון) כדי ליצור ולהעתיק את האסימון.

3. הופכים את האסימון לזמין לגרסאות build לניפוי באגים של האפליקציה בלי להוסיף אותו לקוד המקור. התייחסו לטוקן כמו לפרטי כניסה ואל תכללו אותו בניהול הגרסאות. לדוגמה, אפשר להוסיף אותו לקובץ local.properties של הפרויקט, שלא נכלל בניהול הגרסאות:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   לאחר מכן, חושפים אותו כשדה BuildConfig בקובץ build.gradle.kts של המודול (ברמת האפליקציה). בדוגמה הבאה, המערכת גם קוראת משתנה סביבה של FPNV_TEST_TOKEN, שמועיל בשרתי CI שאין בהם קובץ local.properties. גרסאות build להפצה מקבלות ערך ריק:

   // 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. באפליקציה, מפעילים סשן בדיקה פעם אחת לכל תהליך באפליקציה:

   Kotlin

   הפונקציה FirebasePhoneNumberVerification.getInstance() מחזירה את אותו מופע של ברירת המחדל של FirebaseApp בכל פעם שקוראים לה, לכן צריך להשתמש בה לכל הקריאות ל-Firebase PNV.

   צריך להפעיל את enableTestSession() רק פעם אחת בכל תהליך של האפליקציה. קריאה שנייה גורמת ל-FirebasePhoneNumberVerificationException עם קוד השגיאה TEST_SESSION_ALREADY_ENABLED, לכן אל תפעילו אותה מ-Activity, שאפשר ליצור מחדש (לדוגמה, כשהמסך מסתובב). במקום זאת, קוראים לה מהמחלקה 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)
       }
   }
   

   רושמים את המחלקה בקובץ המניפסט של האפליקציה:

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

ה-TTL של טוקנים לבדיקה הוא 7 ימים. אחרי התקופה הזו, תצטרכו ליצור טוקן חדש כדי להפעיל סשנים של בדיקה. טוקן שפג תוקפו לא גורם לשגיאה עד שקוראים ל-getVerifiedPhoneNumber(). אסימוני בדיקה פועלים במכשירים פיזיים ובאמולטורים שיש בהם את Google Play Services, ולכן הם אידיאליים ליצירת אב טיפוס של חוויית המשתמש באפליקציה. אתם יכולים גם להשתמש בהם לבדיקה ב-CI/CD אם אתם מחליפים את האסימון לפחות כל 7 ימים.

האסימונים של מספרי הטלפון שהאפליקציה מקבלת במצב בדיקה חתומים כמו אסימונים בסביבת הייצור, אבל הם כוללים את ההצהרה "test_number": true. חשוב לוודא שה-backend בסביבת הייצור דוחה טוקנים עם ההצהרה הזו.

3. מומלץ: לבדוק אם יש תמיכה ב-Firebase PNV

כדי לעזור לכם לקבוע מתי להציג את ממשק המשתמש להזנת מספר או את ממשק המשתמש להסבר, מומלץ לבדוק אם המכשיר וכרטיס ה-SIM שלו תומכים ב-Firebase PNV בזמן הפעלת האפליקציה. זו בדיקה מקדימה שלא דורשת הסכמה מהמשתמש. אתם יכולים להשתמש בתוצאה של הבדיקה הזו כדי להחליט אם להפעיל את התהליך של Firebase PNV או להשתמש בשיטה חלופית לאימות מספר הטלפון, כמו SMS.

כדי לבדוק אם המכשיר תואם, מפעילים את ה-method‏ getVerificationSupportInfo(). בזמן שסשן הבדיקה פעיל, ה-method הזו תמיד מחזירה רשימה שמכילה רשומה נתמכת אחת לטוקן הבדיקה, בלי ליצור קשר עם הקצה העורפי של Firebase PNV. כלומר, אי אפשר להפעיל את החלופה למכשירים לא נתמכים במצב בדיקה. בהמשך, אחרי שתעבירו את האפליקציה לסביבת הייצור, השיטה הזו תחזיר תוצאה לכל כרטיס SIM במכשיר.

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. התחלת תהליך האימות

כדי להתחיל את התהליך של Firebase PNV, צריך להפעיל את ה-method‏ getVerifiedPhoneNumber(). מעבירים Activity, כי השיטה מציגה את מסך ההסכמה. Context שהוא לא Activity, כמו ההקשר של Application, נכשל עם קוד השגיאה 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.
    }

השיטה getVerifiedPhoneNumber() מבצעת את כל תהליך האימות של מספר הטלפון, כולל:

• שימוש ב-Android Credential Manager כדי לקבל את הסכמת המשתמש לשיתוף מספר הטלפון שלו.
• שליחת הבקשה לקצה העורפי של Firebase PNV.
• החזרת אסימון שמכיל את מספר הטלפון המאומת של המכשיר (באפליקציה בסביבת ייצור, זה השלב שבו מתבצע החיוב).

5. טיפול בשגיאות

כשקריאה ל-Firebase PNV נכשלת, החריגה היא FirebasePhoneNumberVerificationException. אפשר להשתמש ב-errorCode כדי להחליט מה לעשות בהמשך, למשל לחזור לאימות באמצעות SMS אם המשתמש לא נותן הסכמה. במאמר טיפול בשגיאות של Firebase PNV ב-Android מפורטים כל קודי השגיאה, מתי הם מתרחשים והפעולה המומלצת.

השלבים הבאים

• בדף הזה מוסבר איך לשלב את Firebase PNV באמצעות ה-API המאוחד לקריאה אחת. קריאה ל-method יחיד מטפלת בכל מסלול המשתמש ב-Firebase PNV, החל מקבלת הסכמה מהמשתמש ועד לביצוע הקריאות הנדרשות לרשת אל ה-backend של Firebase PNV. כשמשתמשים בשיטה הזו, שלבי השילוב מצטמצמים להפעלת method אחת.

  ה-API הזה מומלץ לרוב המפתחים. עם זאת, אם יש לכם דרישות ספציפיות שהספרייה לא עונה עליהן, אתם יכולים לעיין בדף התאמה אישית של תהליך Firebase Phone Number Verification כדי לקבל מידע על הטמעה של תהליך מותאם אישית.

• אם אתם משתמשים במספר הטלפון המאומת מחוץ ללקוח האפליקציה, כדאי להעביר את הטוקן במקום את מספר הטלפון עצמו, כדי שתוכלו לאמת את התקינות שלו כשתשתמשו בו. אימות אסימוני Firebase PNV

• כדי להכניס משתמשים ל-Firebase Authentication באמצעות מספר הטלפון המאומת שלהם, קראו את המאמר אימות באמצעות Firebase באמצעות Firebase Phone Number Verification.

• כדי לראות הדרכה מפורטת ליצירת אפליקציה מלאה לדוגמה, נסו את ה-codelab של Firebase Phone Number Verification.

• אחרי שהטמעתם ובדקתם את תהליך ה-Firebase PNV של האפליקציה ואת השילוב עם הקצה העורפי, אתם יכולים להעביר את האפליקציה לסביבת הייצור כדי להתחיל לקבל מספרי טלפון מאומתים אמיתיים. שדרוג למצב ייצור

• ל-API המלא, קראו את מאמרי העזרה של ‎Firebase PNV API‎.