Bắt đầu sử dụng tính năng Xác minh số điện thoại của Firebase trên Android

Trang này mô tả cách bắt đầu sử dụng Firebase Phone Number Verification trong một ứng dụng Android. Hãy xem tổng quan để biết thông tin mô tả chung về tính năng này.

Bằng cách làm theo các bước trên trang này, bạn có thể nhanh chóng bắt đầu triển khai luồng người dùng cho Firebase PNV. Để thử nghiệm, bạn sẽ tạo một mã thông báo chỉ dùng để thử nghiệm, mã này sẽ phân giải thành một số điện thoại giả. Khi sử dụng mã thông báo thử nghiệm này, bạn có thể bắt đầu thêm Firebase PNV vào ứng dụng mà không cần tài khoản thanh toán hoặc thiết bị có SIM thực.

Sau khi hài lòng với trải nghiệm người dùng Firebase PNV trong ứng dụng, bạn có thể làm theo một số bước bổ sung để đưa ứng dụng vào chính thức hoạt động.

Trước khi bắt đầu

• Thêm Firebase vào dự án Android nếu bạn chưa thực hiện.

• Đảm bảo ứng dụng của bạn đáp ứng các yêu cầu sau:

  • minSdk của ứng dụng là 24 (Android 7.0) trở lên.
  • Thiết bị hoặc trình mô phỏng có Dịch vụ Google Play. Đối với trình mô phỏng, hãy sử dụng một hình ảnh hệ thống có Google Play.
  • Để xác minh số điện thoại thực trong môi trường phát hành công khai, thiết bị phải chạy Android 9 (cấp độ API 28) trở lên và sử dụng SIM của một nhà mạng được hỗ trợ. Chế độ kiểm thử (được mô tả trên trang này) không cần SIM thực.

1. Thêm thư viện Firebase PNV vào ứng dụng của bạn

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

Bằng cách sử dụng Firebase Android BoM, ứng dụng của bạn sẽ luôn sử dụng những phiên bản tương thích của thư viện Android trên Firebase.

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. Khởi chạy thư viện Firebase PNV ở chế độ thử nghiệm

1. Trong bảng điều khiển Firebase, hãy chuyển đến thẻ Bảo mật > Xác minh qua điện thoại > Cài đặt > Thử nghiệm.

2. Nhấp vào Tạo mã thông báo, chọn mã quốc gia, rồi nhấp vào Tạo mã thông báo một lần nữa để tạo và sao chép mã thông báo.

3. Cung cấp mã thông báo để gỡ lỗi các bản dựng của ứng dụng mà không cần cố định giá trị trong mã nguồn. Hãy coi mã thông báo như thông tin xác thực và không đưa mã thông báo vào hệ thống quản lý phiên bản. Ví dụ: thêm tệp này vào tệp local.properties của dự án, tệp này không được kiểm tra trong chế độ quản lý phiên bản:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Sau đó, hiển thị tệp này dưới dạng trường BuildConfig trong tệp build.gradle.kts của mô-đun (cấp ứng dụng). Ví dụ sau đây cũng đọc một biến môi trường FPNV_TEST_TOKEN, biến này hữu ích trên các máy chủ CI không có tệp local.properties. Bản phát hành nhận được giá trị trống:

   // 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. Trong ứng dụng, hãy bật một phiên kiểm thử cho mỗi quy trình ứng dụng:

   Kotlin

   FirebasePhoneNumberVerification.getInstance() trả về cùng một thực thể cho FirebaseApp mặc định mỗi khi bạn gọi, vì vậy, hãy sử dụng thực thể này cho tất cả lệnh gọi Firebase PNV.

   Chỉ gọi enableTestSession() một lần cho mỗi quy trình ứng dụng. Lần gọi thứ hai sẽ gửi một FirebasePhoneNumberVerificationException có mã lỗi TEST_SESSION_ALREADY_ENABLED, vì vậy, đừng gọi phương thức này từ một Activity có thể được tạo lại (ví dụ: khi màn hình xoay). Thay vào đó, hãy gọi hàm này từ lớp 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)
       }
   }
   

   Đăng ký lớp trong tệp kê khai ứng dụng:

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

Mã thông báo kiểm thử có TTL là 7 ngày; sau khoảng thời gian này, bạn sẽ cần tạo một mã thông báo mới để bật phiên kiểm thử. Mã thông báo đã hết hạn sẽ không gây ra lỗi cho đến khi bạn gọi getVerifiedPhoneNumber(). Mã thông báo kiểm thử hoạt động trên các thiết bị thực và trình mô phỏng có Dịch vụ Google Play, giúp bạn dễ dàng tạo nguyên mẫu trải nghiệm người dùng trong ứng dụng. Bạn cũng có thể dùng mã thông báo kiểm thử để kiểm thử trong CI/CD nếu thay thế mã thông báo ít nhất 7 ngày một lần.

Mã thông báo số điện thoại mà ứng dụng của bạn nhận được ở chế độ thử nghiệm được ký như mã thông báo phát hành công khai, nhưng có chứa thông báo xác nhận quyền sở hữu "test_number": true. Hãy đảm bảo rằng phần phụ trợ chính thức của bạn từ chối mã thông báo có thông báo xác nhận quyền sở hữu này.

3. Nên làm: Kiểm tra khả năng hỗ trợ Firebase PNV

Để giúp bạn xác định thời điểm hiển thị giao diện người dùng nhập số hoặc giao diện người dùng giải thích, khi khởi chạy ứng dụng, bạn nên kiểm tra xem thiết bị và thẻ SIM của thiết bị có hỗ trợ Firebase PNV hay không. Đây là bước kiểm tra trước và không cần sự đồng ý của người dùng. Bạn có thể sử dụng kết quả của quy trình kiểm thử này để quyết định xem có nên bắt đầu quy trình Firebase PNV hay sử dụng một phương thức xác minh số điện thoại thay thế, chẳng hạn như SMS.

Để kiểm tra khả năng tương thích của thiết bị, hãy gọi phương thức getVerificationSupportInfo(). Khi bạn có một phiên kiểm thử đang hoạt động, phương thức này luôn trả về một danh sách chứa một mục được hỗ trợ duy nhất cho mã thông báo kiểm thử mà không cần liên hệ với phần phụ trợ Firebase PNV. Điều này có nghĩa là bạn không thể thực hiện phương án dự phòng cho thiết bị không được hỗ trợ ở chế độ thử nghiệm. Sau này, khi bạn đưa ứng dụng vào chính thức, phương thức này sẽ trả về kết quả cho từng SIM trong thiết bị.

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. Bắt đầu quy trình xác minh

Để bắt đầu quy trình Firebase PNV, hãy gọi phương thức getVerifiedPhoneNumber(). Truyền Activity vì phương thức này hiển thị màn hình xin phép. Context không phải là Activity, chẳng hạn như bối cảnh Application, sẽ không thành công và trả về mã lỗi 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.
    }

Phương thức getVerifiedPhoneNumber() thực hiện toàn bộ quy trình xác minh số điện thoại, bao gồm:

• Sử dụng Trình quản lý thông tin xác thực Android để yêu cầu người dùng đồng ý chia sẻ số điện thoại của họ.
• Gửi yêu cầu đến phần phụ trợ Firebase PNV.
• Trả về một mã thông báo chứa số điện thoại đã xác minh cho thiết bị (trong một ứng dụng chính thức, đây là thời điểm tính phí).

5. Xử lý lỗi

Khi lệnh gọi Firebase PNV không thành công, ngoại lệ sẽ là FirebasePhoneNumberVerificationException. Sử dụng errorCode của nó để quyết định việc cần làm tiếp theo, chẳng hạn như quay lại quy trình xác minh qua SMS khi người dùng từ chối đồng ý. Hãy xem bài viết Xử lý lỗi Firebase PNV trên Android để biết mọi mã lỗi, thời điểm xảy ra lỗi và hành động được đề xuất.

Các bước tiếp theo

• Trang này trình bày chi tiết cách tích hợp với Firebase PNV bằng API hợp nhất, một lệnh gọi. Việc gọi một phương thức duy nhất sẽ xử lý toàn bộ luồng người dùng Firebase PNV, từ việc lấy sự đồng ý của người dùng đến việc thực hiện các lệnh gọi mạng cần thiết đến phần phụ trợ Firebase PNV. Bằng cách sử dụng phương thức này, bạn sẽ giảm các bước tích hợp xuống còn một lệnh gọi phương thức duy nhất.

  Hầu hết nhà phát triển nên dùng API này. Tuy nhiên, nếu bạn có các yêu cầu cụ thể mà thư viện không đáp ứng được, hãy xem trang Tuỳ chỉnh quy trình Firebase Phone Number Verification để biết thông tin về cách triển khai quy trình tuỳ chỉnh.

• Nếu sử dụng số điện thoại đã xác minh bên ngoài ứng dụng khách, bạn nên chuyển mã thông báo thay vì chính số điện thoại để có thể xác minh tính toàn vẹn của số điện thoại khi sử dụng. Xem phần Xác minh mã thông báo Firebase PNV.

• Để cho phép người dùng đăng nhập vào Firebase Authentication bằng số điện thoại đã xác minh, hãy xem bài viết Xác thực bằng Firebase bằng Firebase Phone Number Verification.

• Để xem hướng dẫn từng bước về cách xây dựng một ứng dụng mẫu hoàn chỉnh, hãy thử tham gia lớp học lập trình Firebase Phone Number Verification.

• Sau khi triển khai và thử nghiệm quy trình Firebase PNV cũng như tích hợp phần phụ trợ của ứng dụng, bạn có thể đưa ứng dụng vào phiên bản chính thức để bắt đầu nhận số điện thoại đã xác minh thực tế. Xem phần Nâng cấp lên chế độ sản xuất.

• Để biết toàn bộ API, hãy xem Tài liệu tham khảo API Firebase PNV.