واجهة برمجة التطبيقات SafetyNet reCAPTCHA

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تتضمّن خدمة SafetyNet واجهة برمجة تطبيقات reCAPTCHA التي يمكنك استخدامها لحماية تطبيقك من الزيارات الضارّة.

reCAPTCHA هي خدمة مجانية تستخدم محرّكًا متقدمًا لتحليل المخاطر بهدف حماية تطبيقك من المحتوى غير المرغوب فيه والإجراءات المسيئة الأخرى. إذا كانت الخدمة تشتبه في أنّ المستخدم الذي يتفاعل مع تطبيقك قد يكون برنامجًا للتتبُّع بدلاً من مستخدم حقيقي، تعرِض اختبار CAPTCHA على المستخدم الحقيقي لحلّه قبل أن يتمكن تطبيقك من مواصلة التنفيذ.

يوضّح هذا المستند كيفية دمج واجهة برمجة التطبيقات reCAPTCHA من SafetyNet في تطبيقك.

بنود الخدمة الإضافية

عند الوصول إلى واجهة برمجة التطبيقات reCAPTCHA API أو استخدامها، يعني ذلك أنّك توافق على بنود خدمة Google APIs وعلى بنود خدمة reCAPTCHA التالية. يُرجى قراءة جميع الأحكام والسياسات السارية وفهمها قبل الوصول إلى واجهات برمجة التطبيقات.

تسجيل مفتاحَي reCAPTCHA

لتسجيل مفتاحَي تشفير لاستخدامهما مع واجهة برمجة التطبيقات SafetyNet reCAPTCHA API، انتقِل إلى موقع الاشتراك في reCAPTCHA لنظام التشغيل Android، ثم أكمِل التسلسل التالي من الخطوات:

1. في النموذج الذي يظهر، أدخِل المعلومات التالية:

   • التصنيف: وهو تصنيف فريد لمفتاحك. عادةً ما يتم استخدام اسم شركتك أو مؤسستك.
   • نوع reCAPTCHA: اختَر الإصدار 2 من reCAPTCHA، ثم reCAPTCHA لنظام التشغيل Android.
   • الحزم: أدخِل اسم حزمة كل تطبيق يستخدم مفتاح واجهة برمجة التطبيقات هذا. لكي يتمكّن التطبيق من استخدام واجهة برمجة التطبيقات، يجب أن يتطابق اسم الحزمة الذي تُدخله تمامًا مع اسم حزمة التطبيق. أدخِل كل اسم حزمة في سطر منفصل.
   • المالكيّن: أضِف عنوان بريد إلكتروني لكل فرد في مؤسستك يرصد تقييمات reCAPTCHA لتطبيقك.

2. ضَع علامة في مربّع الاختيار قبول بنود خدمة reCAPTCHA.

3. إرسال تنبيهات إلى المالكين: ضَع علامة في مربّع الاختيار هذا إذا كنت تريد تلقّي رسائل إلكترونية بشأن واجهة برمجة التطبيقات reCAPTCHA API، ثم انقر على إرسال.

4. في الصفحة التي تظهر بعد ذلك، يظهر المفتاحان العام والخاص ضمن مفتاح الموقع ومفتاح السري، على التوالي. يتم استخدام مفتاح الموقع الإلكتروني عند إرسال طلب التحقّق، ويتم استخدام المفتاح السري عند التحقّق من صحة رمز استجابة المستخدم.

إضافة التبعية لواجهة برمجة التطبيقات SafetyNet

قبل استخدام واجهة برمجة التطبيقات reCAPTCHA API، أضِف واجهة برمجة التطبيقات SafetyNet API إلى مشروعك. إذا كنت تستخدم Android Studio، أضِف هذا الاعتماد إلى ملف Gradle على مستوى التطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد واجهة برمجة التطبيقات SafetyNet API.

استخدام واجهة برمجة تطبيقات reCAPTCHA

يصف هذا القسم كيفية طلب بيانات من واجهة برمجة تطبيقات reCAPTCHA لإرسال طلب التحقّق من CAPTCHA وتلقّي الرمز المميّز لردّ المستخدم.

إرسال طلب إثبات الملكية

لاستدعاء واجهة برمجة تطبيقات SafetyNet reCAPTCHA، يمكنك استدعاء الأسلوب verifyWithRecaptcha(). تتوافق هذه الطريقة عادةً مع اختيار المستخدِم لعنصر واجهة مستخدِم، مثل زر، في نشاطك.

عند استخدام الأسلوب verifyWithRecaptcha() في تطبيقك، يجب إجراء ما يلي:

• أدخِل مفتاح موقعك الإلكتروني لواجهة برمجة التطبيقات كمَعلمة.
• يمكنك إلغاء الطريقتَين 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 بشكل صحيح. لا يزال عليك إثبات صحة الرمز المميّز للردّ الخاص بالمستخدم من خادم الخلفية.

لمعرفة كيفية التحقّق من صحة رمز تنشيط الردّ الخاص بالمستخدم، اطّلِع على مقالة التحقّق من ردّ المستخدم.