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

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

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

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

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

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

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

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

1. في النموذج الذي يظهر، يُرجى تقديم المعلومات التالية:

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

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

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

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

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

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

استخدام reCAPTCHA API

يصف هذا القسم طريقة طلب واجهة برمجة تطبيقات 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 لطريقة onSuccess()، يكون المستخدم قد أكمل تحدي CAPTCHA بنجاح. ومع ذلك، تشير هذه الطريقة فقط إلى أن المستخدم قد حل اختبار CAPTCHA بشكل صحيح. لا تزال بحاجة إلى التحقق من صحة الرمز المميز لاستجابة المستخدم من خادم الخلفية.

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