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

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

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

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

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

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

بنود خدمة reCAPTCHA

تشير موافقتك إلى إقرارك وفهمك أنّ واجهة برمجة التطبيقات reCAPTCHA API تعمل من خلال جمع معلومات عن الأجهزة والبرامج، مثل بيانات الأجهزة والتطبيقات و نتائج عمليات التحقّق من السلامة، وإرسال هذه البيانات إلى Google لتحليلها. بموجب القسم 3(د) من بنود خدمة Google APIs، تتمّ الموافقة على أنّه في حال استخدَمت واجهات برمجة التطبيقات، تقع عليك مسؤولية توفير أي إشعارات أو موافقات لازمة لجمع مثل هذه البيانات ومشاركتها مع Google.

تسجيل مفتاحَي تشفير 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 API، يمكنك استدعاء الأسلوب verifyWithRecaptcha(). تتوافق هذه الطريقة عادةً مع اختيار المستخدِم لعنصر واجهة مستخدِم، مثل زرّ، في نشاطك.

عند استخدام الأسلوب verifyWithRecaptcha() في تطبيقك، يجب إجراء ما يلي:

  • أدخِل مفتاح موقعك الإلكتروني لواجهة برمجة التطبيقات كمَعلمة.
  • يمكنك إلغاء الطريقتَين onSuccess() وonFailure() للتعامل مع كلتا النتيجتَين المحتمَلتين لمهمّة طلب التحقّق. على سبيل المثال، إذا كانت واجهة برمجة التطبيقات تُرسل مثيلًا من ApiException إلى onFailure()، عليك معالجة كل رمز حالة ممكن يمكنك استرجاعه باستخدام getStatusCode().

يوضِّح مقتطف الرمز التالي كيفية استدعاء هذه الطريقة:

Kotlin

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}")
                }
            })
}

Java

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

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