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

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

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

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