تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

طلب إثبات الملكية عبر الرسائل القصيرة SMS في تطبيق Android

لإثبات ملكية أرقام الهواتف تلقائيًا، يجب تنفيذ جزءَي العميل والخادم من عملية إثبات الملكية. تصف هذه الوثيقة كيفية تنفيذ جزء العميل في تطبيق Android.

لبدء عملية إثبات ملكية رقم الهاتف في أحد تطبيقات Android، عليك إرسال رقم الهاتف إلى خادم إثبات الملكية والاتصال بواجهة برمجة تطبيقات SMS Retriever API لبدء الاستماع إلى رسالة SMS تحتوي على رمز يُستخدم لمرة واحدة لتطبيقك. وبعد تلقّي الرسالة، يمكنك إعادة إرسال الرمز الذي يُستخدم لمرة واحدة إلى خادمك لإكمال عملية إثبات الملكية.

قبل البدء

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

المتطلّبات الأساسية للتطبيق

يُرجى التأكُّد من أنّ ملف الإصدار لتطبيقك يستخدم القيم التالية:

الإصدار 19 من حزمة minSdkVersion أو الإصدارات الأعلى
الإصدار 28 أو إصدار أعلى منcom SQLSdkVersion

إعداد تطبيقك

في ملف Build.gradle على مستوى المشروع، ضمِّن مستودع Maven من Google ومستودع Maven المركزي في كل من القسمين buildscript وallprojects:

buildscript {
    repositories {
        google()
        mavenCentral()
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

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

dependencies {
  implementation 'com.google.android.gms:play-services-auth:21.2.0'
  implementation 'com.google.android.gms:play-services-auth-api-phone:18.1.0'
}

1- الحصول على رقم هاتف المستخدم

يمكنك الحصول على رقم هاتف المستخدم بأي طريقة تناسب تطبيقك. غالبًا ما تكون أفضل تجربة للمستخدم هي استخدام منتقي التلميحات لمطالبة المستخدم بالاختيار من بين أرقام الهواتف المخزّنة على الجهاز وبذلك يتجنّب الاضطرار إلى كتابة رقم الهاتف يدويًا. لاستخدام أداة اختيار التلميحات:

// Construct a request for phone numbers and show the picker
private void requestHint() {
    HintRequest hintRequest = new HintRequest.Builder()
           .setPhoneNumberIdentifierSupported(true)
           .build();

    PendingIntent intent = Auth.CredentialsApi.getHintPickerIntent(
            apiClient, hintRequest);
    startIntentSenderForResult(intent.getIntentSender(),
            RESOLVE_HINT, null, 0, 0, 0);
}

// Obtain the phone number from the result
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == RESOLVE_HINT) {
      if (resultCode == RESULT_OK) {
          Credential credential = data.getParcelableExtra(Credential.EXTRA_KEY);
          // credential.getId();  <-- will need to process phone number string
      }
  }
}

‫2. بدء أداة استرداد الرسائل القصيرة

عندما تكون مستعدًا لتأكيد رقم هاتف المستخدم، يمكنك الحصول على نسخة افتراضية من كائن SmsRetrieverClient والاتصال بـ startSmsRetriever وربط مستمعي النجاح والإخفاق بمهمة استرداد الرسائل القصيرة:

// Get an instance of SmsRetrieverClient, used to start listening for a matching
// SMS message.
SmsRetrieverClient client = SmsRetriever.getClient(this /* context */);

// Starts SmsRetriever, which waits for ONE matching SMS message until timeout
// (5 minutes). The matching SMS message will be sent via a Broadcast Intent with
// action SmsRetriever#SMS_RETRIEVED_ACTION.
Task<Void> task = client.startSmsRetriever();

// Listen for success/failure of the start Task. If in a background thread, this
// can be made blocking using Tasks.await(task, [timeout]);
task.addOnSuccessListener(new OnSuccessListener<Void>() {
  @Override
  public void onSuccess(Void aVoid) {
    // Successfully started retriever, expect broadcast intent
    // ...
  }
});

task.addOnFailureListener(new OnFailureListener() {
  @Override
  public void onFailure(@NonNull Exception e) {
    // Failed to start retriever, inspect Exception for more details
    // ...
  }
});

وسوف تستمع مهمة استرداد الرسائل القصيرة SMS لمدة تصل إلى خمس دقائق إلى رسالة قصيرة SMS تحتوي على سلسلة فريدة تحدد تطبيقك.

3- إرسال رقم الهاتف إلى خادمك

بعد الحصول على رقم هاتف المستخدم وبدء الاستماع إلى الرسائل القصيرة SMS، يمكنك إرسال رقم هاتف المستخدم إلى خادم التحقق باستخدام أي طريقة (عادةً باستخدام طلب HTTPS POST).

ينشئ الخادم رسالة تحقق ويرسلها في رسالة قصيرة SMS إلى رقم الهاتف الذي حددته. راجِع إجراء التحقُّق من خلال الرسائل القصيرة SMS على الخادم.

‫4. تلقّي رسائل إثبات الهوية

عند تلقّي رسالة تحقُّق على جهاز المستخدم، تُبثّ "خدمات Play" صراحةً على تطبيقك رسالة Intent التي تتضمّن SmsRetriever.SMS_RETRIEVED_ACTION، والتي تتضمّن نص الرسالة. استخدم BroadcastReceiver لتلقي رسالة التحقق هذه.

في معالج onReceive الخاص بـ BroadcastReceiver، يمكنك الحصول على نص رسالة التحقّق من إضافات Intent:

/**
 * BroadcastReceiver to wait for SMS messages. This can be registered either
 * in the AndroidManifest or at runtime.  Should filter Intents on
 * SmsRetriever.SMS_RETRIEVED_ACTION.
 */
public class MySMSBroadcastReceiver extends BroadcastReceiver {

  @Override
  public void onReceive(Context context, Intent intent) {
    if (SmsRetriever.SMS_RETRIEVED_ACTION.equals(intent.getAction())) {
      Bundle extras = intent.getExtras();
      Status status = (Status) extras.get(SmsRetriever.EXTRA_STATUS);

      switch(status.getStatusCode()) {
        case CommonStatusCodes.SUCCESS:
          // Get SMS message contents
          String message = (String) extras.get(SmsRetriever.EXTRA_SMS_MESSAGE);
          // Extract one-time code from the message and complete verification
          // by sending the code back to your server.
          break;
        case CommonStatusCodes.TIMEOUT:
          // Waiting for SMS timed out (5 minutes)
          // Handle the error ...
          break;
      }
    }
  }
}

يمكنك تسجيل BroadcastReceiver باستخدام فلتر الأهداف com.google.android.gms.auth.api.phone.SMS_RETRIEVED (قيمة الثابت SmsRetriever.SMS_RETRIEVED_ACTION) والإذن com.google.android.gms.auth.api.phone.permission.SEND (قيمة الثابت SmsRetriever.SEND_PERMISSION) في ملف AndroidManifest.xml الخاص بتطبيقك، كما في المثال التالي، أو بشكل ديناميكي باستخدام Context.registerReceiver.

<receiver android:name=".MySMSBroadcastReceiver" android:exported="true"
          android:permission="com.google.android.gms.auth.api.phone.permission.SEND">
    <intent-filter>
        <action android:name="com.google.android.gms.auth.api.phone.SMS_RETRIEVED"/>
    </intent-filter>
</receiver>

5- إرسال الرمز الذي يُستخدم لمرة واحدة من رسالة إثبات الملكية إلى خادمك

الآن بعد أن أصبح لديك نص رسالة التحقق، استخدم تعبيرًا عاديًا أو أي منطق آخر للحصول على الرمز الذي يُستخدم لمرة واحدة من الرسالة. يعتمد تنسيق التعليمة البرمجية لمرة واحدة على كيفية تنفيذها في الخادم.

أخيرًا، أرسل الرمز الذي يُستخدم لمرة واحدة إلى خادمك عبر اتصال آمن. وعندما يتلقى خادمك الرمز الذي يُستخدم لمرة واحدة، فإنه يسجل أن رقم الهاتف قد تم التحقق منه.