میانای برنامه‌سازی کاربردی SafetyNet reCAPTCHA

سرویس SafetyNet شامل یک «میانای برنامه‌سازی کاربردی reCAPTCHA» است که می‌توانید از آن برای محافظت از برنامه خود دربرابر ترافیک مخرب استفاده کنید.

‫reCAPTCHA سرویسی رایگان است که از موتور تحلیل خطر پیشرفته‌ای برای محافظت از برنامه شما دربرابر هرزنامه و دیگر کنش‌های سوءاستفاده‌گرانه استفاده می‌کند. اگر سرویس مشکوک شود که کاربری که با برنامه شما تعامل دارد ممکن است روبات باشد نه انسان، یک CAPTCHA ارائه می‌کند که انسان باید آن را حل کند تا برنامه شما بتواند به اجرا ادامه دهد.

این سند نحوه ادغام کردن reCAPTCHA API از SafetyNet در برنامه شما را توضیح می‌دهد.

شرایط خدمات تکمیلی

با دسترسی به یا استفاده از «میانای برنامه‌سازی کاربردی reCAPTCHA»، با شرایط خدمات Google APIs و «شرایط خدمات reCAPTCHA» زیر موافقت می‌کنید. لطفاً قبل‌از دسترسی به «میاناهای برنامه‌سازی کاربردی»، همه شرایط و خط‌مشی‌های ذی‌ربط را بخوانید و درک کنید.

ثبت جفت کلید reCAPTCHA

برای ثبت جفت کلید برای استفاده با «میانای برنامه‌سازی کاربردی SafetyNet reCAPTCHA»، به سایت ثبت‌نام reCAPTCHA ویژه Android بروید، سپس توالی مراحل زیر را تکمیل کنید:

1. در فرمی که ظاهر می‌شود، اطلاعات زیر را ارائه دهید:

   • برچسب: برچسبی منحصربه‌فرد برای کلید شما. معمولاً از نام شرکت یا سازمانتان استفاده می‌کنید.
   • نوع reCAPTCHA: reCAPTCHA v2 و سپس reCAPTCHA Android را انتخاب کنید.
   • بسته‌ها: نام بسته هر برنامه‌ای را که از این کلید API استفاده می‌کند ارائه دهید. برای اینکه برنامه‌ای بتواند از API استفاده کند، نام بسته‌ای که وارد می‌کنید باید دقیقاً با نام بسته برنامه مطابقت داشته باشد. نام هر بسته را در خط جداگانه‌ای وارد کنید.
   • مالکان: برای هر فرد در سازمانتان که ارزیابی‌های reCAPTCHA برنامه شما را پایش می‌کند نشانی ایمیل اضافه کنید.

2. چارگوش پذیرفتن «شرایط خدمات reCAPTCHA» را انتخاب کنید.

3. ارسال هشدار به مالکان: اگر می‌خواهید ایمیل‌هایی درباره «میانای برنامه‌سازی کاربردی reCAPTCHA» دریافت کنید، این چارگوش انتخاب را انتخاب کنید، سپس روی ارسال کلیک کنید.

4. در صفحه‌ای که در مرحله بعد ظاهر می‌شود، کلیدهای عمومی و خصوصی شما به‌ترتیب در بخش‌های کلید سایت و کلید محرمانه نمایش داده می‌شوند. هنگام ارسال درخواست درستی‌سنجی از کلید سایت استفاده می‌کنید و هنگام اعتبارسنجی رمز پاسخ کاربر از کلید مخفی استفاده می‌کنید.

وابستگی SafetyNet API را اضافه کنید

قبل‌از استفاده از reCAPTCHA API،‏ SafetyNet API را به پروژه‌تان اضافه کنید. اگر از Android Studio استفاده می‌کنید، این وابستگی را به فایل Gradle سطح برنامه خود اضافه کنید. برای اطلاعات بیشتر، راه‌اندازی SafetyNet API را ببینید.

استفاده از reCAPTCHA API

این بخش نحوه فراخوانی API reCAPTCHA را برای ارسال درخواست درستی‌سنجی CAPTCHA و دریافت کد پاسخ کاربر شرح می‌دهد.

ارسال درخواست درستی‌سنجی

برای فراخوانی کردن SafetyNet reCAPTCHA API، روش verifyWithRecaptcha() را فراخوانی می‌کنید. معمولاً، این روش با انتخاب عنصر رابط کاربری توسط کاربر، مثل دکمه، در فعالیت شما مطابقت دارد.

هنگام استفاده از روش verifyWithRecaptcha() در برنامه‌تان، باید کارهای زیر را انجام دهید:

• کلید سایت API خود را به‌عنوان پارامتر ارسال کنید.
• روش‌های onSuccess() و onFailure() را ملغی کنید تا هر دو نتیجه ممکن از وظیفه درخواست درستی‌سنجی را مدیریت کنید. به‌طور خاص، اگر «میانای برنامه‌سازی کاربردی» نمونه‌ای از ApiException را به onFailure() منتقل می‌کند، باید هر کد وضعیت ممکن را که می‌توانید بااستفاده از getStatusCode() بازیابی کنید مدیریت کنید.

تکه‌کد زیر نحوه فراخوانی این روش را نشان می‌دهد:

fun onClick(view: View) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
            .addOnSuccessListener(this as Executor, OnSuccessListener { response ->
                // Indicates communication with reCAPTCHA service was
                // successful.
                val userResponseToken = response.tokenResult
                if (response.tokenResult?.isNotEmpty() == true) {
                    // Validate the user response token using the
                    // reCAPTCHA siteverify API.
                }
            })
            .addOnFailureListener(this as Executor, OnFailureListener { e ->
                if (e is ApiException) {
                    // An error occurred when communicating with the
                    // reCAPTCHA service. Refer to the status code to
                    // handle the error appropriately.
                    Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")
                } else {
                    // A different, unknown type of error occurred.
                    Log.d(TAG, "Error: ${e.message}")
                }
            })
}

public void onClick(View v) {
    SafetyNet.getClient(this).verifyWithRecaptcha(YOUR_API_SITE_KEY)
        .addOnSuccessListener((Executor) this,
            new OnSuccessListener<SafetyNetApi.RecaptchaTokenResponse>() {
                @Override
                public void onSuccess(SafetyNetApi.RecaptchaTokenResponse response) {
                    // Indicates communication with reCAPTCHA service was
                    // successful.
                    String userResponseToken = response.getTokenResult();
                    if (!userResponseToken.isEmpty()) {
                        // Validate the user response token using the
                        // reCAPTCHA siteverify API.
                    }
                }
        })
        .addOnFailureListener((Executor) this, new OnFailureListener() {
                @Override
                public void onFailure(@NonNull Exception e) {
                    if (e instanceof ApiException) {
                        // An error occurred when communicating with the
                        // reCAPTCHA service. Refer to the status code to
                        // handle the error appropriately.
                        ApiException apiException = (ApiException) e;
                        int statusCode = apiException.getStatusCode();
                        Log.d(TAG, "Error: " + CommonStatusCodes
                                .getStatusCodeString(statusCode));
                    } else {
                        // A different, unknown type of error occurred.
                        Log.d(TAG, "Error: " + e.getMessage());
                    }
                }
        });
}

کد پاسخ کاربر را اعتبارسنجی کنید

وقتی reCAPTCHA API روش onSuccess() را اجرا می‌کند، کاربر چالش CAPTCHA را باموفقیت تکمیل کرده است. بااین‌حال، این روش فقط نشان می‌دهد که کاربر CAPTCHA را به‌درستی حل کرده است. همچنان باید کد پاسخ کاربر را از سرور زیرینه‌تان درستی‌سنجی کنید.

برای آشنایی با نحوه اعتبارسنجی کد پاسخ کاربر، به درستی‌سنجی پاسخ کاربر مراجعه کنید.