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

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

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

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

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

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

تسجيل زوج مفاتيح reCAPTCHA

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

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

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

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

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

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

إضافة تبعية SafetyNet API

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

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