Как начать работу с подтверждением номера телефона Firebase на Android

На этой странице рассказывается, как начать использовать Firebase Phone Number Verification в приложении для Android. Общее описание этой функции приведено в обзорной статье.

Следуя инструкциям на этой странице, вы сможете быстро начать реализацию путей пользователя для Firebase PNV. Для тестирования вы создадите токен, который будет разрешаться в поддельный номер телефона. С помощью этого тестового токена вы можете начать добавлять Firebase PNV в свое приложение, не используя платежный аккаунт или устройство с настоящей SIM-картой.

Когда вы будете довольны тем, как Firebase PNV работает в вашем приложении, вы можете выполнить дополнительные шаги, чтобы подготовить приложение к выпуску.

Подготовка

• Если вы ещё этого не сделали, добавьте Firebase в проект для Android.

• Убедитесь, что ваше приложение соответствует следующим требованиям:

  • Значение minSdk вашего приложения – 24 (Android 7.0) или выше.
  • На устройстве или в эмуляторе есть сервисы Google Play. Для эмуляторов используйте системный образ, включающий 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 перейдите в раздел Security (Безопасность) > Phone Verification (Подтверждение по телефону) > Settings (Настройки) > Testing (Тестирование).

2. Нажмите Создать токен, выберите код страны и снова нажмите Создать токен, чтобы создать и скопировать токен.

3. Сделайте токен доступным для отладочных сборок приложения, не задавая его в исходном коде. Обращайтесь с токеном как с учетными данными и не включайте его в систему управления версиями. Например, добавьте его в файл local.properties проекта, который не проверяется системой управления версиями:

   fpnv.testToken=COPIED_TOKEN_STRING
   

   Затем добавьте его в качестве поля BuildConfig в файл build.gradle.kts на уровне модуля (приложения). В примере ниже также считывается переменная среды FPNV_TEST_TOKEN, что полезно на серверах непрерывной интеграции, на которых нет файла 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. Включите тестовый сеанс в приложении один раз для каждого процесса:

   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"
       ... >
   

Срок действия тестовых токенов составляет семь дней. По истечении этого периода вам нужно будет сгенерировать новый токен, чтобы включить тестовые сеансы. Просроченный токен не вызывает ошибку, пока вы не вызовете getVerifiedPhoneNumber(). Тестовые токены работают на физических устройствах и эмуляторах с сервисами Google Play, поэтому они идеально подходят для создания прототипов UX в приложении. Вы также можете использовать их для тестирования в CI/CD, если будете заменять токен не реже одного раза в 7 дней.

Токены номера телефона, которые ваше приложение получает в тестовом режиме, подписываются так же, как и рабочие токены, но включают утверждение "test_number": true. Убедитесь, что ваш рабочий сервер отклоняет токены с этим утверждением.

3. Рекомендуется: проверьте поддержку Firebase PNV

Чтобы определить, когда показывать интерфейс ввода номера или объяснения, при запуске приложения рекомендуется проверить, поддерживают ли устройство и его SIM-карта Firebase PNV. Это предварительная проверка, которая не требует согласия пользователя. Результат этой проверки поможет вам решить, использовать ли Firebase PNV или альтернативный метод подтверждения номера телефона, например SMS.

Чтобы проверить совместимость устройства, вызовите метод getVerificationSupportInfo(). Пока тестовый сеанс активен, этот метод всегда возвращает список, содержащий одну поддерживаемую запись для тестового токена, без обращения к серверной части 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, вызовите метод 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 для получения согласия пользователя на передачу его номера телефона.
• Отправка запроса на сервер 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.

• Пошаговые инструкции по созданию примера приложения вы найдете в практической работе по Firebase Phone Number Verification.

• После того как вы реализовали и протестировали процесс Firebase PNV и интеграцию с сервером, вы можете запустить приложение в производство, чтобы начать получать реальные проверенные номера телефонов. См. Переход в производственный режим.

• Полное описание API приведено в документации по Firebase PNV API.