SafetyNet reCAPTCHA API

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

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

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

شرایط خدمات اضافی

با دسترسی یا استفاده از API reCAPTCHA، شما با شرایط خدمات APIهای گوگل و شرایط خدمات reCAPTCHA زیر موافقت می‌کنید. لطفاً قبل از دسترسی به APIها، تمام شرایط و سیاست‌های مربوطه را مطالعه و درک کنید.

یک جفت کلید reCAPTCHA ثبت کنید

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

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

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

2. کادر انتخاب «شرایط خدمات reCAPTCHA را بپذیرید» را علامت بزنید.

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

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

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

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

از رابط برنامه‌نویسی reCAPTCHA استفاده کنید

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

درخواست تأیید را ارسال کنید

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

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

• کلید سایت API خود را به عنوان پارامتر ارسال کنید.
• متدهای onSuccess() و onFailure() را برای مدیریت هر دو نتیجه‌ی ممکن از وظیفه‌ی درخواست تأیید، بازنویسی کنید. به طور خاص، اگر API نمونه‌ای از 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 را به درستی حل کرده است. شما هنوز باید توکن پاسخ کاربر را از سرور backend خود اعتبارسنجی کنید.

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