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

۱. نمای کلی

«درستی‌سنجی شماره تلفن Firebase» (Firebase PNV یا FPNV) روشی سریع‌تر و ایمن‌تر برای درستی‌سنجی شماره تلفن است. برخلاف درستی‌سنجی مبتنی بر پیامک که کاربران نهایی را ملزم می‌کند کدی را از پیامک دریافت و وارد کنند، «درستی‌سنجی شماره تلفن Firebase» با دریافت مستقیم شماره تلفن اختصاص‌داده‌شده به سیم‌کارت در دستگاه از شرکت مخابراتی متصل با یک ضربه کار می‌کند. این کار اصطکاک کاربر نهایی را کاهش می‌دهد، با عدم وابستگی به تحویل پیامک، قابلیت اطمینان را بهبود می‌بخشد، و بردارهای سوءاستفاده‌ای را که معمولاً هنگام استفاده از پیامک مورد بهره‌برداری قرار می‌گیرند حذف می‌کند.

در این کدآزمایی، یاد می‌گیرید چگونه یک کارگزار صوتی هوش مصنوعی «یابنده رستوران» بسازید که از «درستی‌سنجی شماره تلفن Firebase» برای درستی‌سنجی شماره تلفن کاربر نهایی قبل‌از تأیید رزرو میز استفاده می‌کند.

پیش‌نیازها

• جدیدترین نسخه استودیو Android
• دستگاه Android یا شبیه‌ساز با «سطح میانای برنامه‌سازی کاربردی ۲۶» یا بالاتر

آنچه خواهید آموخت

• پروژه Firebase را با Firebase PNV راه‌اندازی کنید.
• از Firebase PNV در حالت آزمایش استفاده کنید تا بدون حساب صورت‌حساب یا سیم‌کارت واقعی نمونه اولیه بسازید.
• کیت توسعه نرم‌افزار Firebase PNV را در برنامه Android ادغام کنید.
• شماره تلفن را بااستفاده از «میانای برنامه‌سازی کاربردی تک‌تماس» درستی‌سنجی کنید.
• (اختیاری) برنامه‌تان را برای تولید آماده کنید.

۲. راه‌اندازی پروژه نمونه

ایجاد پروژه Firebase

1. بااستفاده از «حساب Google» خود به سیستم کنسول Firebase وارد شوید.
2. برای ایجاد پروژه جدید، روی دکمه کلیک کنید و سپس نام پروژه را وارد کنید (برای مثال، Tera Bites).
   
3. روی ادامه کلیک کنید.
4. درصورت درخواست، شرایط Firebase را مرور و تأیید کنید، و سپس روی ادامه کلیک کنید.
5. (اختیاری) «دستیار هوش مصنوعی» را در کنسول Firebase فعال کنید (به آن «Gemini در Firebase» گفته می‌شود).
6. برای این کدآزمایی، به Google Analytics نیاز ندارید، بنابراین گزینه Google Analytics را خاموش کنید.
7. روی ایجاد پروژه کلیک کنید، منتظر بمانید تا پروژه شما آماده شود، و سپس روی ادامه دادن کلیک کنید.

بارگیری کد

برای شبیه‌سازی کد نمونه این codelab، فرمان‌های زیر را اجرا کنید:

git clone https://github.com/GoogleCloudPlatform/devrel-demos
cd codelabs/firebase-pnv-android

دایرکتوری firebase-pnv-android را در «استودیو Android» باز کنید.

پروژه Android خود را به Firebase متصل کنید

1. در کنسول Firebase، در مرکز صفحه نمای کلی پروژه، روی نماد Android یا افزودن برنامه کلیک کنید تا گردش کار ایجاد برنامه راه‌اندازی شود.
2. در فیلد نام بسته Android، نام بسته برنامه را وارد کنید: com.google.firebase.example.fpnv.
3. روی ثبت برنامه کلیک کنید.
4. دستورالعمل‌های بارگیری فایل google-services.json را دنبال کنید و آن را به فهرست راهنمای app/ کد بارگیری‌شده منتقل کنید.
5. روی بعدی کلیک کنید.

فعال کردن Firebase AI Logic

این codelab از Firebase AI Logic برای تقویت عامل صوتی هوش مصنوعی استفاده می‌کند. برای فعال کردن Firebase AI Logic در پروژه Firebase خود:

1. در کنسول Firebase، به خدمات هوش مصنوعی > منطق هوش مصنوعی بروید.
2. روی شروع به کار کلیک کنید.
3. با کلیک کردن روی شروع به کار با این API، استفاده از Gemini Developer API را انتخاب کنید.
4. بقیه مراحل گردش کار راه‌اندازی گام‌به‌گام را ادامه دهید.

۳. راه‌اندازی Firebase PNV در حالت آزمایش

حالت آزمایش به شما امکان می‌دهد شماره تلفن «جعلی» را بااستفاده از کد آزمایشی برای توسعه درستی‌سنجی کنید.

به برنامه بتای عمومی «خدمات سیستم Google» بپیوندید

برای استفاده از حالت آزمایشی، دستگاه توسعه‌تان را در کانال بتای خدمات سیستم Google ثبت کنید:

1. به صفحه آزمایش برنامه Android - خدمات سیستم Google مرور کنید.
2. روی گزینه تبدیل شدن به یک آزمایش‌گر کلیک کنید.

اکنون آزمایش‌گر بتا برای «خدمات سیستم Google» هستید.

افزودن وابستگی Firebase PNV

در پایگاه کد پروژه Android شما، وابستگی‌های کتابخانه‌های Firebase PNV و Firebase AI Logic ازقبل در فایل /gradle/versions.toml تعریف شده است:

[versions]
# ... other dependencies
firebaseBom = "34.13.0"

[libraries]
# ... other libraries
firebase-bom = { module = "com.google.firebase:firebase-bom", version.ref = "firebaseBom" }
firebase-ai-logic = { module = "com.google.firebase:firebase-ai" }
firebase-pnv = { module = "com.google.firebase:firebase-pnv" }

در فایل Gradle واحد (سطح برنامه) (معمولاً /app/build.gradle.kts)، وابستگی کتابخانه Firebase PNV را اعلام کنید:

dependencies {
  // ... other dependencies
  implementation(platform(libs.firebase.bom))
  implementation(libs.firebase.ai.logic)

  // Add this line
  implementation(libs.firebase.pnv)

  // ...
}

تولید کردن کد آزمایشی

1. در کنسول Firebase، به امنیت > درستی‌سنجی تلفن بروید.
2. برگه آزمایش را انتخاب کنید.
3. کد کشور شماره تلفن آزمایشی خود را انتخاب کنید و روی تولید کد کلیک کنید.
4. رشته کد تولیدشده را کپی کنید.

فعال کردن جلسه آزمایش در کد

1. در پروژه Android خود، فایل ChatViewModel.kt را باز کنید و تابع verifyPhoneNumber() را پیدا کنید.
2. کارخواه FirebasePhoneNumberVerification را مقداردهی اولیه کنید و جلسه آزمایش را فعال کنید، و نشانی را که از کنسول Firebase کپی کرده‌اید جای‌گذاری کنید:

   suspend fun verifyPhoneNumber(): String {
       // Initialize Firebase Phone Number Verification
       val fpnv = FirebasePhoneNumberVerification.getInstance()
   
       // Enable Test session
       fpnv.enableTestSession("PASTE_THE_TOKEN_YOU_COPIED_IN_PREV_STEP")
   
       // Trigger the Firebase PNV pop up
       val response = fpnv.getVerifiedPhoneNumber(context!!).await()
       val phoneNumber = response.getPhoneNumber()
   
       return phoneNumber
   }
   

۴. اجرای برنامه

اکنون که Firebase PNV را پیاده‌سازی کرده‌اید، زمان اجرای برنامه است.

1. در Android Studio، روی اجرا کردن کلیک کنید تا برنامه در شبیه‌ساز Android یا در دستگاه فیزیکی راه‌اندازی شود.
2. پس‌از راه‌اندازی برنامه، باید صفحه‌ای شبیه به این ببینید:
   
3. روی شروع تماس کلیک کنید و خودتان را معرفی کنید.
   
4. نماینده صوتی هوش مصنوعی باید جزئیات رزرو را از شما بپرسد. پس‌از ارائه جزئیات، باید از شما خواسته شود که به صفحه‌نمایش نگاه کنید تا شماره تلفنتان را درستی‌سنجی کنید:
   
5. پس‌از انجام این کار، صفحه تکمیل درستی‌سنجی را خواهید دید:
   
6. برای پایان دادن به تماس، روی پایان جلسه کلیک کنید.

۵. (اختیاری) ارتقا دادن به حالت تولید

ارتقا دادن طرح قیمت‌گذاری Firebase

برای استفاده از Firebase PNV در حالت تولید، پروژه Firebase شما باید در طرح قیمت‌گذاری براساس مصرف (Blaze) باشد، که یعنی به حساب صورت‌حساب Cloud پیوند داده شده باشد.

• حساب «صورت‌حساب Cloud» به روش پرداخت، مانند کارت اعتباری، نیاز دارد.
• درطول تبلیغات ویژه یا اگر این codelab را به‌عنوان بخشی از یک رویداد انجام می‌دهید، ممکن است اعتبارات Google Cloud دردسترس باشد.
• اگر با Firebase و Google Cloud آشنایی ندارید، بررسی کنید که آیا واجدشرایط ۳۰۰ دلار اعتبار و حساب «صورت‌حساب Cloud» دوره آزمایشی رایگان هستید یا نه.

برای ارتقا دادن پروژه به طرح Blaze، این مراحل را دنبال کنید:

1. در کنسول Firebase، ارتقا دادن طرح را انتخاب کنید.
2. طرح Blaze را انتخاب کنید. دستورالعمل‌های روی صفحه را برای پیوند دادن حساب Cloud Billing به پروژه‌تان دنبال کنید.
   
   • اگر برای این کدآزمایی از اعتبارهای Google Cloud استفاده می‌کنید، احتمالاً نام حساب صورت‌حساب Google Cloud Platform Trial Billing Account یا My Billing Account است.
   • اگر لازم بود به‌عنوان بخشی از این ارتقا، حساب «صدور صورت‌حساب Cloud» ایجاد کنید، ممکن است لازم باشد برای تکمیل ارتقا به جریان ارتقا در کنسول Firebase برگردید.

فعال کردن حالت تولید Firebase PNV

1. اثر انگشت SHA-256 برنامه‌تان را اضافه کنید:
   1. در کنسول Firebase، به صفحه تنظیمات > کلی بروید.
   2. به کارت برنامه‌های شما پیمایش کنید و برنامه Android خود را پیدا کنید.
   3. اثر انگشت SHA-256 خود را به فیلد اثر انگشت‌های گواهینامه SHA اضافه کنید. برای جزئیات مربوط به نحوه دریافت اثر انگشت SHA-256 برنامه‌تان، به اصالت‌سنجی مشتری مراجعه کنید.
2. به امنیت > درستی‌سنجی تلفن برگردید.
3. روی راه‌اندازی تولید کلیک کنید. فهرستی از برنامه‌های موجود در پروژه‌تان را که برای تولید فعال خواهند شد مشاهده خواهید کرد و فرصت خواهید داشت برنامه‌های دیگری اضافه کنید.
4. برنامه‌تان را برای درستی‌سنجی نمانام OAuth و مرور خط‌مشی رازداری ارسال کنید. ‫Google Cloud درستی‌سنجی خواهد کرد که برنامه و خط‌مشی رازداری آن را به‌طور واضح و دقیق مشخص کرده‌اید.
   برای شروع بازبینی، روی ادامه در Google Cloud کلیک کنید. این فرایند گاهی اوقات ممکن است ۲۴ ساعت یا بیشتر طول بکشد.
5. درحالی‌که منتظر درستی‌سنجی نمانام هستید، شرایط خاص سرویس Firebase PNV را که در کنسول پیوند داده شده است مرور کنید.
6. پس‌از اینکه برنامه شما درستی‌سنجی نمانام را گذراند، چارگوش را علامت بزنید تا شرایط ویژه خدمات را تأیید کنید، و سپس روی فعال کردن کلیک کنید.

‫Firebase PNV اکنون در حالت تولید فعال است.

برداشتن کد آزمایش

در پروژه Android خود، خط fpnv.enableTestSession(...) را حذف کنید.

انتقال Firebase AI Logic برای استفاده از «پلاتفرم عامل»

اگر در حساب صورت‌حساب خود از اعتبار استفاده می‌کنید، نمی‌توانید از آن‌ها با Gemini Developer API استفاده کنید. اما می‌توانید از آن‌ها با Agent Platform Gemini API استفاده کنید.

1. در کنسول Firebase، به خدمات هوش مصنوعی > منطق هوش مصنوعی بروید.
2. روی تنظیمات کلیک کنید.
3. در بخش میانای برنامه‌سازی کاربردی پلاتفرم Gemini Agent، روی فعال کردن کلیک کنید.
4. در پروژه Android خود، مقداردهی اولیه Firebase AI Logic را تغییر دهید تا به‌جای Google AI از زیرینه «پلاتفرم عامل» استفاده کند:

   val model = Firebase.ai(
       backend = GenerativeBackend.agentPlatform(location = "us-central1")
   ).liveModel(
       modelName = "gemini-live-2.5-flash-native-audio",
       // ... other configuration
   )
   

‫۶. تبریک!

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

آنچه پوشش داده‌ایم

• درحال راه‌اندازی پروژه برای Firebase PNV.
• از حالت آزمایش برای نمونه‌سازی استفاده می‌شود.
• پیاده‌سازی کردن Firebase PNV single-call API.
• درحال ارتقا به حالت تولید.

مراحل بعدی

• با نحوه سفارشی‌سازی جریان Firebase PNV آشنا شوید.
• با نحوه درستی‌سنجی کردن نشان‌های PNV در Firebase آشنا شوید.
• قیمت‌گذاری و سهمیه‌ها را بررسی کنید.