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

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