SafetyNet reCAPTCHA API

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

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

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

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

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

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

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

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

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

2. تیک گزینه Accept the reCAPTCHA Terms of Service را انتخاب کنید.

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

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

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

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

از reCAPTCHA API استفاده کنید

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

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

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

هنگام استفاده از متد 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 را به درستی حل کرده است. هنوز باید رمز پاسخ کاربر را از سرور باطن خود تأیید کنید.

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

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

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

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

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

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

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

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

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

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

2. تیک گزینه Accept the reCAPTCHA Terms of Service را انتخاب کنید.

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

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

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

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

از reCAPTCHA API استفاده کنید

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

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

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

هنگام استفاده از متد 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 را به درستی حل کرده است. هنوز باید رمز پاسخ کاربر را از سرور باطن خود تأیید کنید.

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