لإثبات ملكية أرقام الهواتف تلقائيًا، عليك تنفيذ كلّ من قسمَي العميل والخادم من عملية إثبات الملكية. يوضِّح هذا المستند كيفية تنفيذ جزء العميل في تطبيق Android.
لبدء عملية إثبات ملكية رقم الهاتف في أحد تطبيقات Android، عليك إرسال رقم الهاتف إلى خادم إثبات الملكية واستدعاء واجهة برمجة التطبيقات SMS Retriever API لبدء الاستماع إلى رسالة SMS تحتوي على رمز صالح لمرة واحدة لتطبيقك. بعدتلقّي الرسالة، عليك إعادة إرسال الرمز الصالح لمرة واحدة إلى خادمك لإكمال عملية إثبات الملكية.
قبل البدء
لإعداد تطبيقك، أكمِل الخطوات الواردة في الأقسام التالية.
متطلبات التطبيق الأساسية
تأكَّد من أنّ ملف إنشاء تطبيقك يستخدم القيم التالية:
- الإصدار 19 من حزمة minSdkVersion أو إصدار أحدث
- compileSdkVersion 28 أو إصدار أحدث
ضبط إعدادات تطبيقك
في ملف 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.3.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
// ...
}
});
ستستمع مهمة استرداد الرسائل القصيرة لمدة تصل إلى خمس دقائق لتلقّي رسالة قصيرة تحتوي على سلسلة فريدة تحدّد تطبيقك.
3- إرسال رقم الهاتف إلى خادمك
بعد الحصول على رقم هاتف المستخدم وبدء الاستماع إلى الرسائل القصيرة، أرسِل رقم هاتف المستخدم إلى خادم التحقّق باستخدام أي طريقة (عادةً باستخدام طلب POST عبر بروتوكول HTTPS).
يُنشئ خادمك رسالة إثبات ملكية ويرسلها عبر رسالة قصيرة (SMS) إلى رقم الهاتف الذي حدّدته. راجِع مقالة تنفيذ عملية إثبات الهوية عبر الرسائل القصيرة على الخادم.
4. تلقّي رسائل إثبات الملكية
عند تلقّي رسالة إثبات الهوية على جهاز المستخدم، تُرسِل "خدمات Play"
بوضوح إلى تطبيقك SmsRetriever.SMS_RETRIEVED_ACTION
Intent،
الذي يحتوي على نص الرسالة. استخدِم BroadcastReceiver
لتلقّي
رسالة التأكيد هذه.
في معالِج BroadcastReceiver
onReceive
، احصل على نص
رسالة التحقّق (وعنوان المُرسِل اختياريًا) من ملف إضافات
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:
// (Optional) Get SMS Sender address - only available in
// GMS version 24.20 onwards, else it will return null
String senderAddress = extras.getString(SmsRetriever.EXTRA_SMS_ORIGINATING_ADDRESS);
// Get SMS message contents
String message = extras.getString(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- أرسِل الرمز المخصّص لمرة واحدة من رسالة إثبات الملكية إلى خادمك.
بعد الحصول على نص رسالة التحقّق، استخدِم تعبيرًا عاديًا أو منطقًا آخر للحصول على الرمز المُستخدَم لمرة واحدة من الرسالة. يعتمد تنسيق الرمز المُستخدَم لمرة واحدة على كيفية تنفيذه في خادمك.
أخيرًا، أرسِل الرمز المخصّص للاستخدام مرة واحدة إلى الخادم من خلال اتصال آمن. عندما يتلقّى خادمك الرمز المخصّص لمرّة واحدة، يسجّل أنّه تم إثبات ملكية رقم الهاتف.