בקשת הסכמה חד-פעמית לקריאת קוד אימות ב-SMS

בדף הזה מוסבר איך להשתמש ב-SMS User Consent API כדי לבקש הסכמה מהמשתמש לקריאת הודעת אימות אחת ב-SMS. אם המשתמש מסכים, ה-API מחזיר את הטקסט של ההודעה, שממנו אפשר לקבל את קוד האימות ולהשלים את תהליך האימות.

התקנת יחסי תלות

כוללים את רכיב האימות של Play Services בקובץ build.gradle של האפליקציה:

implementation 'com.google.android.gms:play-services-auth:17.0.0'
implementation 'com.google.android.gms:play-services-auth-api-phone:17.4.0'

1. קבלת מספר הטלפון של המשתמש

אם אין לכם את מספר הטלפון של המשתמש, תצטרכו לבקש אותו לפני שתתחילו בתהליך אימות באמצעות SMS.

אפשר לקבל את מספר הטלפון של המשתמש באופן שמתאים לאפליקציה שלכם. כדאי להשתמש בכלי לבחירת רמזים של Smart Lock לסיסמאות כדי לעזור למשתמש למלא את מספר הטלפון שלו, אם הפרטים האלה לא נדרשו ליצירת החשבון של המשתמש. כדי להשתמש בבורר הרמזים:

Kotlin

private val CREDENTIAL_PICKER_REQUEST = 1  // Set to an unused request code

// Construct a request for phone numbers and show the picker
private fun requestHint() {
    val hintRequest = HintRequest.Builder()
        .setPhoneNumberIdentifierSupported(true)
        .build()
    val credentialsClient = Credentials.getClient(this)
    val intent = credentialsClient.getHintPickerIntent(hintRequest)
    startIntentSenderForResult(
        intent.intentSender,
        CREDENTIAL_PICKER_REQUEST,
        null, 0, 0, 0
    )
}

public override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    when (requestCode) {
        CREDENTIAL_PICKER_REQUEST ->
            // Obtain the phone number from the result
            if (resultCode == Activity.RESULT_OK && data != null) {
                val credential = data.getParcelableExtra<Credential>(Credential.EXTRA_KEY)
                // credential.getId();  <-- will need to process phone number string
            }
        // ...
    }
}

Java

private static final int CREDENTIAL_PICKER_REQUEST = 1;  // Set to an unused request code

// Construct a request for phone numbers and show the picker
private void requestHint() throws IntentSender.SendIntentException {
    HintRequest hintRequest = new HintRequest.Builder()
            .setPhoneNumberIdentifierSupported(true)
            .build();
    PendingIntent intent = Credentials.getClient(this).getHintPickerIntent(hintRequest);
    startIntentSenderForResult(intent.getIntentSender(),
            RESOLVE_HINT, null, 0, 0, 0);
}

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

2. איך מתחילים להאזין להודעות נכנסות

לאחר מכן, קוראים לשיטה startSmsUserConsent() של SMS User Consent API כדי להתחיל להאזין להודעות נכנסות. אם אתם יודעים את מספר הטלפון שממנו תגיע הודעת ה-SMS, ציינו אותו (אחרת, העבירו null). כך, ה-API להפעלת סטטוס הסכמה של הסכמת המשתמש ל-SMS יופעל רק בהודעות מהמספר הזה.

כדי להתחיל להאזין:

Kotlin

// Start listening for SMS User Consent broadcasts from senderPhoneNumber
// The Task<Void> will be successful if SmsRetriever was able to start
// SMS User Consent, and will error if there was an error starting.
val task = SmsRetriever.getClient(context).startSmsUserConsent(senderPhoneNumber /* or null */)

Java

// Start listening for SMS User Consent broadcasts from senderPhoneNumber
// The Task<Void> will be successful if SmsRetriever was able to start
// SMS User Consent, and will error if there was an error starting.
Task<Void> task = SmsRetriever.getClient(context).startSmsUserConsent(senderPhoneNumber /* or null */);

אחרי שמתחילים להאזין להודעות SMS נכנסות, אפשר לבקש ממערכת האימות לשלוח את קוד האימות למספר הטלפון של המשתמש, שקיבלתם בשלב הראשון.

במשך חמש הדקות הבאות, כשהמכשיר יקבל הודעת SMS שמכילה קוד חד-פעמי, Play Services ישדר לאפליקציה שלכם Intent להציג למשתמש בקשה להרשאה לקרוא את ההודעה. הודעה מפעילה את השידור רק אם היא עומדת בקריטריונים הבאים:

• ההודעה מכילה מחרוזת אלפאנומרית באורך 4-10 תווים עם מספר אחד לפחות.
• אם ציינתם את מספר הטלפון של השולח, ההודעה נשלחה מהמספר הזה.

כדי לטפל בשידורים האלה, צריך להשתמש ב-broadcast receiver עם הרשאה SEND_PERMISSION שמגיב ל-intents של SMS_RETRIEVED_ACTION. כדי ליצור ולרשום את מקלט השידור:

Kotlin

private val SMS_CONSENT_REQUEST = 2  // Set to an unused request code
private val smsVerificationReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        if (SmsRetriever.SMS_RETRIEVED_ACTION == intent.action) {
            val extras = intent.extras
            val smsRetrieverStatus = extras?.get(SmsRetriever.EXTRA_STATUS) as Status

            when (smsRetrieverStatus.statusCode) {
                CommonStatusCodes.SUCCESS -> {
                    // Get consent intent
                    val consentIntent = extras.getParcelable<Intent>(SmsRetriever.EXTRA_CONSENT_INTENT)
                    try {
                        // Start activity to show consent dialog to user, activity must be started in
                        // 5 minutes, otherwise you'll receive another TIMEOUT intent
                        startActivityForResult(consentIntent, SMS_CONSENT_REQUEST)
                    } catch (e: ActivityNotFoundException) {
                        // Handle the exception ...
                    }
                }
                CommonStatusCodes.TIMEOUT -> {
                    // Time out occurred, handle the error.
                }
            }
        }
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    val intentFilter = IntentFilter(SmsRetriever.SMS_RETRIEVED_ACTION)
    registerReceiver(smsVerificationReceiver, SmsRetriever.SEND_PERMISSION, intentFilter)
}

Java

private static final int SMS_CONSENT_REQUEST = 2;  // Set to an unused request code
private final BroadcastReceiver smsVerificationReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (SmsRetriever.SMS_RETRIEVED_ACTION.equals(intent.getAction())) {
            Bundle extras = intent.getExtras();
            Status smsRetrieverStatus = (Status) extras.get(SmsRetriever.EXTRA_STATUS);

            switch (smsRetrieverStatus.getStatusCode()) {
                case CommonStatusCodes.SUCCESS:
                    // Get consent intent
                    Intent consentIntent = extras.getParcelable(SmsRetriever.EXTRA_CONSENT_INTENT);
                    try {
                        // Start activity to show consent dialog to user, activity must be started in
                        // 5 minutes, otherwise you'll receive another TIMEOUT intent
                        startActivityForResult(consentIntent, SMS_CONSENT_REQUEST);
                    } catch (ActivityNotFoundException e) {
                        // Handle the exception ...
                    }
                    break;
                case CommonStatusCodes.TIMEOUT:
                    // Time out occurred, handle the error.
                    break;
            }
        }
    }
};

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // ...

    IntentFilter intentFilter = new IntentFilter(SmsRetriever.SMS_RETRIEVED_ACTION);
    registerReceiver(smsVerificationReceiver, SmsRetriever.SEND_PERMISSION, intentFilter);
}

כשמפעילים פעילות עבור EXTRA_CONSENT_INTENT, מוצגת למשתמש בקשה להרשאה חד-פעמית לקריאת תוכן ההודעה.

חשוב: כדי לזהות שה-intent של השידור הוא מ-SMS Retriever API, צריך להוסיף את ההרשאה com.google.android.gms.auth.api.phone.permission.SEND לרכיב המקבל. הגדרת ההרשאה הזו זמינה בגרסה 19.8.31 ואילך של Google Play Services.

חשוב: אל תוסיפו את ההרשאה com.google.android.gms.auth.api.phone.permission.SEND לאפליקציה שלכם. ההרשאה הזו צריכה לשמש רק כדי לזהות שהכוונה היא מ-SMS Retriever API ב-מקלט שידורים.

3. קבלת קוד האימות מהודעה

בשיטה onActivityResult(), מטפלים בתגובה של המשתמש לבקשת ההרשאה. אם מקבלים קוד תוצאה RESULT_OK, המשתמש העניק הרשאה לקרוא את תוכן ההודעה, ואפשר לקבל את הטקסט של ההודעה מה-Intent.

Kotlin

public override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    when (requestCode) {
        // ...
        SMS_CONSENT_REQUEST ->
            // Obtain the phone number from the result
            if (resultCode == Activity.RESULT_OK && data != null) {
                // Get SMS message content
                val message = data.getStringExtra(SmsRetriever.EXTRA_SMS_MESSAGE)
                // Extract one-time code from the message and complete verification
                // `message` contains the entire text of the SMS message, so you will need
                // to parse the string.
                val oneTimeCode = parseOneTimeCode(message) // define this function

                // send one time code to the server
            } else {
                // Consent denied. User can type OTC manually.
            }
    }
}

Java

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    switch (requestCode) {
        // ...
        case SMS_CONSENT_REQUEST:
            if (resultCode == RESULT_OK) {
                // Get SMS message content
                String message = data.getStringExtra(SmsRetriever.EXTRA_SMS_MESSAGE);
                // Extract one-time code from the message and complete verification
                // `sms` contains the entire text of the SMS message, so you will need
                // to parse the string.
                String oneTimeCode = parseOneTimeCode(message); // define this function

                // send one time code to the server
            } else {
                // Consent canceled, handle the error ...
            }
            break;
    }
}

אחרי שמקבלים את הטקסט של ההודעה, אפשר לנתח את קוד האימות ולאכלס אוטומטית את הטופס, או להשלים את תהליך האימות בדרך אחרת.