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

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

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

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

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

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

بنود خدمة reCAPTCHA

أنت تُقر وتفهم أنّ واجهة برمجة تطبيقات reCAPTCHA تعمل عن طريق جمع معلومات عن الأجهزة والبرامج، مثل بيانات الجهاز والتطبيق و نتائج عمليات التحقّق من السلامة، ثم إرسال هذه البيانات إلى 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، يمكنك استدعاء الأسلوب 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 بشكل صحيح. لا يزال عليك إثبات صحة الرمز المميّز للردّ الخاص بالمستخدم من خادم الخلفية.

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