تلميح بشأن رقم الهاتف

توفّر واجهة برمجة التطبيقات Phone Number Hint API (واجهة برمجة التطبيقات لرقم الهاتف) ضمن خدمات Google Play طريقة سلسة لعرض أرقام هاتف المستخدم (المستندة إلى شريحة SIM) كتلميح.

تشمل مزايا استخدام "تلميح رقم الهاتف" ما يلي:

  • لا حاجة إلى تقديم طلبات أذونات إضافية
  • لن يحتاج المستخدم إلى كتابة رقم الهاتف يدويًا.
  • لا حاجة إلى حساب Google
  • غير مرتبط مباشرةً بعمليات سير عمل تسجيل الدخول أو الاشتراك
  • توفير المزيد من الدعم لإصدارات Android مقارنةً بميزة "الملء التلقائي"

قبل البدء

لإعداد تطبيقك، أكمِل الخطوات الواردة في الأقسام التالية.

ضبط إعدادات تطبيقك

أضِف تبعية خدمات Google Play لواجهة برمجة التطبيقات Phone Number Hint API إلى ملف إصدار Gradle للوحدة، والذي يكون عادةً app/build.gradle:

  apply plugin: 'com.android.application'

  ...

  dependencies {
    implementation 'com.google.android.gms:play-services-auth:21.0.0'
  }

آلية العمل

تستخدم واجهة برمجة التطبيقات Phone Number Hint API PendingIntent لبدء التدفق. بمجرد إطلاق PendingIntent، سيتم عرض المستخدم بواجهة مستخدم تُدرج جميع أرقام الهواتف (المستندة إلى شريحة SIM). يمكن للمستخدم بعد ذلك اختيار تحديد رقم الهاتف الذي يريد استخدامه أو إلغاء التدفق. ستتم إتاحة رقم الهاتف المحدد للمطوِّر للحصول عليه من Intent.

واجهة المستخدم والإعدادات الخاصة بتلميح رقم الهاتف
الشكل 1. واجهة المستخدم والإعدادات الخاصة بتلميح رقم الهاتف

إنشاء كائن GetPhoneNumbeHintIntentRequest

ابدأ بإنشاء عنصر GetPhoneNumberHintIntentRequest باستخدام الطريقة GetPhoneNumberHintIntentRequest.Builder() المقدّمة. يمكن بعد ذلك استخدام كائن الطلب هذا للحصول على Intent لبدء تدفق "تلميح رقم الهاتف".

Kotlin

val request: GetPhoneNumberHintIntentRequest = GetPhoneNumberHintIntentRequest.builder().build()

Java

GetPhoneNumberHintIntentRequest request = GetPhoneNumberHintIntentRequest.builder().build();

جارٍ طلب تلميح رقم الهاتف

يمكنك استدعاء SignInClient.getPhoneNumberHintIntent()، بتمرير عنصر GetPhoneNumberHintIntentRequest السابق، لاسترداد PendingIntent لبدء مسار "تلميح رقم الهاتف".

Kotlin

val phoneNumberHintIntentResultLauncher = ...

Identity.getSignInClient(activity)
.getPhoneNumberHintIntent(request)
.addOnSuccessListener { result: PendingIntent ->
  try {
    phoneNumberHintIntentResultLauncher.launch(
      IntentSenderRequest.Builder(result).build()
    )
  } catch (e: Exception) {
      Log.e(TAG, "Launching the PendingIntent failed")
  }
}
.addOnFailureListener {
    Log.e(TAG, "Phone Number Hint failed")
}

Java

ActivityResultLauncher phoneNumberHintIntentResultLauncher = ...

Identity.getSignInClient(activity)
  .getPhoneNumberHintIntent(request)
  .addOnSuccessListener( result -> {
      try {
          phoneNumberHintIntentResultLauncher.launch(result.getIntentSender());
      } catch(Exception e) {
          Log.e(TAG, "Launching the PendingIntent failed", e);
      }
  })
  .addOnFailureListener(e -> {
      Log.e(TAG, "Phone Number Hint failed", e);
  });

استرداد رقم الهاتف

مرِّر Intent إلى SignInClient.getPhoneNumberFromIntent لاسترداد رقم الهاتف.

Kotlin

val phoneNumberHintIntentResultLauncher =
registerForActivityResult(ActivityResultContracts.StartIntentSenderForResult()) { result ->
      try {
          val phoneNumber = Identity.getSignInClient(activity).getPhoneNumberFromIntent(result.data)
      } catch(e: Exception) {
          Log.e(TAG, "Phone Number Hint failed")
      }
  }

Java

ActivityResultLauncher phoneNumberHintIntentResultLauncher =
  registerForActivityResult(
      new ActivityResultContracts.StartActivityForResult(),
      new ActivityResultCallback() {
          @Override
          public void onActivityResult(ActivityResult result) {
              try {
                  String phoneNumber = Identity.getSignInClient(activity).getPhoneNumberFromIntent(result.getData());
              } catch {
                  Log.e(TAG, "Phone Number Hint failed", e);
              }
          }
  });