เริ่มต้นใช้งานการยืนยันหมายเลขโทรศัพท์ด้วย Firebase ใน Android

หน้านี้อธิบายวิธีเริ่มต้นใช้งาน Firebase Phone Number Verification ในแอป Android ดูคำอธิบายทั่วไปของฟีเจอร์นี้ได้ที่ภาพรวม

เมื่อทำตามขั้นตอนในหน้านี้ คุณจะเริ่มใช้โฟลว์ผู้ใช้สำหรับ Firebase PNV ได้อย่างรวดเร็ว เพื่อวัตถุประสงค์ในการทดสอบ คุณจะต้องสร้างโทเค็นสำหรับการทดสอบเท่านั้นซึ่งจะแปลงเป็นหมายเลขโทรศัพท์ปลอม เมื่อใช้โทเค็นทดสอบนี้ คุณจะเริ่มเพิ่ม Firebase PNV ลงในแอปได้โดยไม่ต้องมีบัญชีสำหรับการเรียกเก็บเงินหรืออุปกรณ์ที่มีซิมจริง

เมื่อพอใจกับประสบการณ์ของผู้ใช้ Firebase PNV ในแอปแล้ว คุณสามารถทำตามขั้นตอนเพิ่มเติมเพื่อทำให้แอปพร้อมใช้งานจริงได้

ก่อนเริ่มต้น

• เพิ่ม Firebase ลงในโปรเจ็กต์ Android หากยังไม่ได้เพิ่ม

• ตรวจสอบว่าแอปเป็นไปตามข้อกำหนดต่อไปนี้

  • minSdk ของแอปคือ 24 (Android 7.0) ขึ้นไป
  • อุปกรณ์หรือโปรแกรมจำลองมีบริการ Google Play สำหรับโปรแกรมจำลอง ให้ใช้ภาพระบบที่มี Google Play
  • หากต้องการยืนยันหมายเลขโทรศัพท์จริงในเวอร์ชันที่ใช้งานจริง อุปกรณ์ต้องใช้ Android 9 (ระดับ API 28) ขึ้นไปและใช้ซิมจากผู้ให้บริการที่รองรับ โหมดทดสอบที่อธิบายไว้ในหน้านี้ไม่จำเป็นต้องใช้ซิมจริง

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. คลิกสร้างโทเค็น เลือกรหัสประเทศ แล้วคลิกสร้างโทเค็นอีกครั้งเพื่อสร้างและคัดลอกโทเค็น

3. ทำให้โทเค็นพร้อมใช้งานสำหรับบิลด์การแก้ไขข้อบกพร่องของแอปโดยไม่ต้องฮาร์ดโค้ดในซอร์สโค้ด โปรดดูแลโทเค็นให้เหมือนกับข้อมูลเข้าสู่ระบบและเก็บไว้นอกการควบคุมเวอร์ชัน เช่น เพิ่มลงในไฟล์ local.properties ของโปรเจ็กต์ ซึ่งไม่ได้เช็คอินลงในการควบคุมเวอร์ชัน

   fpnv.testToken=COPIED_TOKEN_STRING
   

   จากนั้นแสดงเป็นช่อง BuildConfig ในไฟล์ build.gradle.kts ระดับโมดูล (ระดับแอป) ตัวอย่างต่อไปนี้ยังอ่านตัวแปรสภาพแวดล้อม FPNV_TEST_TOKEN ด้วย ซึ่งมีประโยชน์ในเซิร์ฟเวอร์ CI ที่ไม่มีไฟล์ local.properties บิลด์ที่เผยแพร่จะได้รับค่าว่าง ดังนี้

   // 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. ในแอป ให้เปิดใช้เซสชันทดสอบ 1 ครั้งต่อกระบวนการของแอป โดยทำดังนี้

   Kotlin

   FirebasePhoneNumberVerification.getInstance() จะแสดงผลอินสแตนซ์เดียวกันสำหรับ FirebaseApp เริ่มต้นทุกครั้งที่คุณเรียกใช้ ดังนั้นให้ใช้เมธอดนี้สำหรับการเรียกใช้ Firebase PNV ทั้งหมด

   เรียกใช้ enableTestSession() เพียงครั้งเดียวต่อกระบวนการของแอป การเรียกครั้งที่ 2 จะแสดง 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)
       }
   }
   

   ลงทะเบียนคลาสในไฟล์ Manifest ของแอป ดังนี้

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

โทเค็นทดสอบมี TTL 7 วัน หลังจากระยะเวลานี้ คุณจะต้องสร้างโทเค็นใหม่เพื่อเปิดใช้เซสชันทดสอบ โทเค็นที่หมดอายุจะไม่ทำให้เกิดข้อผิดพลาดจนกว่าคุณจะเรียกใช้ getVerifiedPhoneNumber() โทเค็นทดสอบจะทำงานในอุปกรณ์จริงและโปรแกรมจำลองที่มีบริการ Google Play จึงเหมาะอย่างยิ่งสำหรับการสร้างต้นแบบ UX ในแอป นอกจากนี้ คุณยังใช้โทเค็นทดสอบสำหรับการทดสอบใน CI/CD ได้ด้วยหากเปลี่ยนโทเค็นอย่างน้อยทุก 7 วัน

โทเค็นหมายเลขโทรศัพท์ที่แอปได้รับในโหมดทดสอบจะได้รับการรับรองเหมือนโทเค็นเวอร์ชันที่ใช้งานจริง แต่จะมีคำกล่าวอ้าง "test_number": true ตรวจสอบว่าแบ็กเอนด์เวอร์ชันที่ใช้งานจริงปฏิเสธโทเค็นที่มีการอ้างสิทธิ์นี้

3. แนะนำ: ตรวจสอบการรองรับ Firebase PNV

เพื่อช่วยคุณพิจารณาว่าจะแสดง UI การป้อนหมายเลขหรือ UI อธิบายเมื่อใด เราขอแนะนำให้ตรวจสอบว่าอุปกรณ์และซิมการ์ดรองรับ Firebase PNV หรือไม่เมื่อเปิดแอป ซึ่งเป็นการตรวจสอบล่วงหน้าที่ไม่ต้องได้รับความยินยอมจากผู้ใช้ คุณสามารถใช้ผลลัพธ์ของการทดสอบนี้เพื่อตัดสินใจว่าจะเริ่มขั้นตอน Firebase PNV หรือใช้วิธีอื่นในการยืนยันหมายเลขโทรศัพท์ เช่น SMS

หากต้องการตรวจสอบความเข้ากันได้ของอุปกรณ์ ให้เรียกใช้เมธอด getVerificationSupportInfo() ขณะที่คุณมีเซสชันการทดสอบที่ใช้งานอยู่ เมธอดนี้จะแสดงรายการที่มีรายการเดียวที่รองรับสำหรับโทเค็นทดสอบเสมอ โดยไม่ต้องติดต่อแบ็กเอนด์ของ Firebase PNV ซึ่งหมายความว่าคุณจะใช้โหมดสำรองสำหรับอุปกรณ์ที่ไม่รองรับในโหมดทดสอบไม่ได้ หลังจากนั้น เมื่อคุณทำให้แอปพร้อมใช้งานจริงแล้ว เมธอดนี้จะแสดงผลลัพธ์สำหรับซิมแต่ละอันในอุปกรณ์

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 ให้เรียกใช้เมธอด 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 แบบเรียกใช้ครั้งเดียวที่รวมเป็นหนึ่งเดียว การเรียกใช้เมธอดเดียวจะจัดการโฟลว์ผู้ใช้ Firebase PNV ทั้งหมด ตั้งแต่การขอความยินยอมของผู้ใช้ไปจนถึงการเรียกใช้เครือข่ายที่จำเป็นไปยังแบ็กเอนด์ Firebase PNV การใช้วิธีนี้จะช่วยลดขั้นตอนการผสานรวมให้เหลือเพียงการเรียกใช้เมธอดเดียว

  เราขอแนะนำ API นี้สำหรับนักพัฒนาแอปส่วนใหญ่ แต่หากคุณมีข้อกำหนดเฉพาะที่ไลบรารีไม่รองรับ โปรดดูข้อมูลเกี่ยวกับการใช้ขั้นตอนที่กำหนดเองในหน้าปรับแต่งขั้นตอน Firebase Phone Number Verification

• หากใช้หมายเลขโทรศัพท์ที่ยืนยันแล้วนอกไคลเอ็นต์แอป คุณควรส่งโทเค็นแทนหมายเลขโทรศัพท์ เพื่อให้คุณสามารถยืนยันความสมบูรณ์ของโทเค็นเมื่อใช้งานได้ ดูยืนยันโทเค็น Firebase PNV

• หากต้องการให้ผู้ใช้ลงชื่อเข้าใช้ Firebase Authentication ด้วยหมายเลขโทรศัพท์ที่ยืนยันแล้ว โปรดดูหัวข้อตรวจสอบสิทธิ์ด้วย Firebase โดยใช้ Firebase Phone Number Verification

• หากต้องการดูคำแนะนำทีละขั้นตอนซึ่งจะสร้างแอปตัวอย่างที่สมบูรณ์ ให้ลองใช้ Codelab ของ Firebase Phone Number Verification

• หลังจากติดตั้งใช้งานและทดสอบขั้นตอน Firebase PNV ของแอปและการผสานรวมแบ็กเอนด์แล้ว คุณสามารถนำแอปไปใช้งานจริงเพื่อเริ่มรับหมายเลขโทรศัพท์ที่ได้รับการยืนยันจริง ดูหัวข้ออัปเกรดเป็นโหมดโปรดักชัน

• ดู API ทั้งหมดได้ที่เอกสารอ้างอิง API ของ Firebase PNV