شروع به کار با «درستی‌سنجی شماره تلفن Firebase» در Android

این صفحه نحوه شروع استفاده از Firebase Phone Number Verification را در برنامه Android شرح می‌دهد. برای شرح کلی این ویژگی، به نمای کلی مراجعه کنید.

با دنبال کردن مراحل این صفحه، می‌توانید به‌سرعت پیاده‌سازی جریان‌های کاربر را برای Firebase PNV شروع کنید. برای اهداف آزمایشی، یک توکن فقط آزمایشی تولید خواهید کرد که به یک شماره تلفن جعلی منتهی می‌شود. بااستفاده از این کد آزمایشی، می‌توانید بدون نیاز به حساب صورت‌حساب یا دستگاهی با سیم‌کارت واقعی، Firebase PNV را به برنامه‌تان اضافه کنید.

وقتی از تجربه کاربری Firebase PNV در برنامه‌تان راضی بودید، می‌توانید چند مرحله دیگر را برای تولیدی کردن برنامه‌تان دنبال کنید.

قبل از شروع

  • اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Android خود اضافه کنید.

  • مطمئن شوید برنامه‌تان الزامات زیر را برآورده می‌کند:

    • minSdk برنامه‌تان ۲۴ (Android 7.0) یا بالاتر باشد.
    • دستگاه یا شبیه‌ساز Android 10 (سطح میانای برنامه‌سازی کاربردی ۲۹) یا بالاتر را اجرا می‌کند و خدمات Google Play دارد. برای شبیه‌سازها، از تصویر سیستم Android 10 یا بالاتر که شامل Google Play است استفاده کنید.
    • برای درستی‌سنجی شماره تلفن‌های واقعی در تولید، دستگاه باید از سیم‌کارت شرکت مخابراتی پشتیبانی‌شده استفاده کند. حالت آزمایشی که در این صفحه شرح داده شده است به سیم‌کارت واقعی نیاز ندارد.

۱. کتابخانه Firebase PNV را به برنامه‌تان اضافه کنید

در فایل Gradle (سطح برنامه) واحدتان (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle)، وابستگی کتابخانه Firebase Phone Number Verification را برای Android اضافه کنید. توصیه می‌کنیم از Firebase Android BoM برای کنترل نسخه‌بندی کتابخانه استفاده کنید. 

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 استفاده خواهد کرد.

(جایگزین)  افزودن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

اگر انتخاب کنید که از Firebase BoM استفاده نکنید، باید هر نسخه کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

توجه داشته باشید که اگر از چند کتابخانه Firebase در برنامه‌تان استفاده می‌کنید، اکیداً توصیه می‌کنیم از BoM برای مدیریت نسخه‌های کتابخانه استفاده کنید تا مطمئن شوید همه نسخه‌ها سازگار هستند. 

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

۲. مقداردهی اولیه کتابخانه 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. در برنامه‌تان، یک جلسه آزمایشی را یک‌بار در هر فرایند برنامه فعال کنید:

    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‏ ۷ روزه هستند؛ پس‌از این دوره، برای فعال کردن جلسه‌های آزمایشی باید توکن جدیدی تولید کنید. کد منقضی‌شده تا زمانی که getVerifiedPhoneNumber() را فراخوانی نکنید، خطایی ایجاد نمی‌کند. نشان‌های آزمایشی در دستگاه‌های فیزیکی و شبیه‌سازهایی که «خدمات Google Play» دارند کار می‌کنند، که این امر آن‌ها را برای نمونه‌سازی اولیه تجربه کاربری در برنامه‌تان ایده‌آل می‌کند. همچنین می‌توانید از آن‌ها برای آزمایش در CI/CD استفاده کنید، به‌شرطی که نشان را حداقل هر ۷ روز یک‌بار جایگزین کنید.

نشان‌های شماره تلفنی که برنامه‌تان در حالت آزمایشی دریافت می‌کند مانند نشان‌های تولید امضا می‌شوند، اما شامل ادعای "test_number": true هستند. مطمئن شوید که بخش پشتی تولید شما کدهای دارای این ادعا را رد می‌کند.

۳. توصیه‌شده: بررسی کنید Firebase PNV پشتیبانی می‌شود یا نه

برای کمک به شما در تعیین زمان نمایش میانای کاربری ورود شماره یا میانای کاربری توضیح‌دهنده، توصیه می‌شود هنگام راه‌اندازی برنامه بررسی کنید که آیا دستگاه و سیم‌کارت آن از Firebase PNV پشتیبانی می‌کنند یا نه. این یک پیش‌بررسی است که به رضایت کاربر نیاز ندارد. می‌توانید از نتیجه این آزمایش برای تصمیم‌گیری درباره اینکه جریان Firebase PNV را شروع کنید یا از روش جایگزین دیگری برای درستی‌سنجی شماره تلفن (مثل پیامک) استفاده کنید بهره ببرید.

برای بررسی سازگاری دستگاه، روش getVerificationSupportInfo() را فراخوانی کنید. وقتی جلسه آزمایشی فعالی دارید، این روش همیشه فهرستی را برمی‌گرداند که حاوی یک ورودی پشتیبانی‌شده برای کد آزمایشی است، بدون اینکه با باطن Firebase PNV تماس بگیرد. یعنی نمی‌توانید در حالت آزمایشی از بازگشت به دستگاه پشتیبانی‌نشده استفاده کنید. بعداً، پس‌از اینکه برنامه‌تان را به مرحله تولید رساندید، این روش برای هر سیم‌کارت موجود در دستگاه نتیجه‌ای برمی‌گرداند.

Kotlin 

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

۴. شروع کردن جریان درستی‌سنجی

برای شروع جریان Firebase PNV، روش getVerifiedPhoneNumber() را فراخوانی کنید. یک Activity را ارسال کنید، زیرا این روش صفحه رضایت را نمایش می‌دهد. Context که Activity نیست، مثل بافت Application، با کد خطای ACTIVITY_CONTEXT_REQUIRED ناموفق می‌شود.

Kotlin 

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.
  • برگرداندن یک کد حاوی شماره تلفن تأییدشده برای دستگاه (در یک برنامه تولید، این زمانی است که صورت‌حساب صادر می‌شود).

۵. مدیریت کردن خطاها

وقتی تماس Firebase PNV ناموفق باشد، استثنا FirebasePhoneNumberVerificationException است. از errorCode آن برای تصمیم‌گیری درباره اقدام بعدی استفاده کنید، برای مثال، وقتی کاربر رضایت نمی‌دهد، به درستی‌سنجی پیامکی برگردید. برای هر کد خطا، زمان وقوع آن، و اقدام توصیه‌شده، به رسیدگی به خطاهای Firebase PNV در Android مراجعه کنید.

مراحل بعدی

  • این صفحه نحوه ادغام با Firebase PNV را بااستفاده از میانای برنامه‌سازی کاربردی یکپارچه و تک‌فراخوانی شرح می‌دهد. فراخوانی یک روش واحد، کل جریان کاربر Firebase PNV را مدیریت می‌کند، از کسب رضایت کاربر تا برقراری تماس‌های شبکه لازم به باطن Firebase PNV. بااستفاده از این روش، مراحل ادغام را به یک فراخوانی روش کاهش می‌دهید.

    این میانای برنامه‌سازی کاربردی برای اکثر توسعه‌دهندگان توصیه می‌شود؛ بااین‌حال، اگر الزامات خاصی دارید که توسط کتابخانه برآورده نمی‌شود، برای اطلاعات بیشتر درباره پیاده‌سازی جریان سفارشی، به صفحه سفارشی‌سازی جریان Firebase Phone Number Verification مراجعه کنید.

  • اگر از شماره تلفن درستی‌سنجی‌شده در خارج از کارخواه برنامه استفاده می‌کنید، باید به‌جای خود شماره تلفن، کد را ارسال کنید تا بتوانید هنگام استفاده از آن، یکپارچگی آن را درستی‌سنجی کنید. درستی‌سنجی کردن نشان‌های Firebase PNV را ببینید.

  • برای وارد کردن کاربران به سیستم Firebase Authentication با شماره تلفن درستی‌سنجی‌شده‌شان، اصالت‌سنجی با Firebase بااستفاده از Firebase Phone Number Verification را ببینید.

  • برای راهنمای گام‌به‌گام ساختن یک برنامه نمونه کامل، Firebase Phone Number Verification codelab را امتحان کنید.

  • پس‌از پیاده‌سازی و آزمایش جریان Firebase PNV برنامه و ادغام با پس‌زمینه، می‌توانید برنامه را در مرحله تولید قرار دهید تا دریافت شماره تلفن‌های درستی‌سنجی‌شده واقعی را شروع کنید. ارتقا به حالت تولید را ببینید.

  • برای مشاهده میانای برنامه‌سازی کاربردی کامل، مرجع میانای برنامه‌سازی کاربردی Firebase PNV را ببینید.