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

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

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

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

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

يعني الوصول إلى واجهة برمجة التطبيقات reCAPTCHA API أو استخدامها أنّك توافق على بنود خدمة 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 API

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

إرسال طلب التحقّق

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

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