واجهة برمجة تطبيقات SafetyNet للتصفّح الآمن

تتميز واجهة برمجة تطبيقات SafetyNet للتصفح الآمن، وهي مكتبة تدعمها خدمات Google Play، بأنها توفر خدمات لتحديد ما إذا كان قد تم تصنيف عنوان URL على أنه تهديد معروف من قِبل Google.

يمكن لتطبيقك استخدام واجهة برمجة التطبيقات هذه لتحديد ما إذا كان Google قد صنّف عنوان URL معيّنًا كتهديد معروف. داخليًا، تنفّذ SafetyNet عميلاً للإصدار 4 من بروتوكول شبكة التصفح الآمن الذي طورته Google. تم تصميم كل من رمز العميل وبروتوكول الشبكة الإصدار 4 للحفاظ على خصوصية المستخدمين والحفاظ على الحد الأدنى من استهلاك البطارية ومعدل نقل البيانات. يمكنك استخدام واجهة برمجة التطبيقات هذه للاستفادة إلى أقصى حد من خدمة "التصفّح الآمن من Google" على نظام التشغيل Android بأفضل طريقة محسَّنة للموارد، وبدون تنفيذ بروتوكول الشبكة.

يشرح هذا المستند كيفية استخدام واجهة برمجة تطبيقات SafetyNet SafeBrowse Lookup API لفحص عنوان URL بحثًا عن تهديدات معروفة.

بنود الخدمة

ويعني استخدامك لواجهة برمجة تطبيقات التصفح الآمن أنك توافق على الالتزام ببنود الخدمة. يُرجى قراءة وفهم كل البنود والسياسات السارية قبل الدخول إلى واجهة برمجة تطبيقات التصفح الآمن.

طلب مفتاح واجهة برمجة تطبيقات Android وتسجيله

قبل استخدام واجهة برمجة التطبيقات للتصفُّح الآمن، عليك إنشاء مفتاح واجهة برمجة تطبيقات Android وتسجيله. لمعرفة خطوات محدّدة، يمكنك الاطّلاع على الصفحة التي تتناول بدء استخدام التصفّح الآمن.

إضافة واجهة برمجة تطبيقات SafetyNet API

قبل استخدام واجهة برمجة تطبيقات التصفح الآمن، أضف واجهة برمجة تطبيقات SafetyNet إلى مشروعك. إذا كنت تستخدم Android Studio، فأضف هذه التبعية إلى ملف Gradle على مستوى التطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الحماية من التهديدات الأمنية باستخدام SafetyNet.

إعداد واجهة برمجة التطبيقات

لاستخدام واجهة برمجة تطبيقات التصفح الآمن، يجب إعداد واجهة برمجة التطبيقات من خلال طلب initSafeBrowsing() والانتظار حتى اكتمالها. يقدم مقتطف الرمز التالي مثالاً:

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing())

Tasks.await(SafetyNet.getClient(this).initSafeBrowsing());

طلب فحص عنوان URL

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

إرسال طلب التحقق من عنوان URL

تُعدّ واجهة برمجة التطبيقات غير مرتبطة بالمخطط، لذا يمكنك تمرير عنوان URL باستخدام مخطط أو بدونه. على سبيل المثال، كلاهما

var url = "https://www.google.com"

String url = "https://www.google.com";

و

var url = "www.google.com"

String url = "www.google.com";

صالحة.

توضح التعليمة البرمجية التالية كيفية إرسال طلب التحقق من عنوان URL:

SafetyNet.getClient(this).lookupUri(
       url,
       SAFE_BROWSING_API_KEY,
       SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
       SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING
)
       .addOnSuccessListener(this) { sbResponse ->
           // Indicates communication with the service was successful.
           // Identify any detected threats.
           if (sbResponse.detectedThreats.isEmpty()) {
               // No threats found.
           } else {
               // Threats found!
           }
       }
       .addOnFailureListener(this) { e: Exception ->
           if (e is ApiException) {
               // An error with the Google Play Services API contains some
               // additional details.
               Log.d(TAG, "Error: ${CommonStatusCodes.getStatusCodeString(e.statusCode)}")

               // Note: If the status code, s.statusCode,
               // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
               // you need to call initSafeBrowsing(). It means either you
               // haven't called initSafeBrowsing() before or that it needs
               // to be called again due to an internal error.
           } else {
               // A different, unknown type of error occurred.
               Log.d(TAG, "Error: ${e.message}")
           }
       }

SafetyNet.getClient(this).lookupUri(url,
         SAFE_BROWSING_API_KEY,
         SafeBrowsingThreat.TYPE_POTENTIALLY_HARMFUL_APPLICATION,
         SafeBrowsingThreat.TYPE_SOCIAL_ENGINEERING)
   .addOnSuccessListener(this,
       new OnSuccessListener<SafetyNetApi.SafeBrowsingResponse>() {
           @Override
           public void onSuccess(SafetyNetApi.SafeBrowsingResponse sbResponse) {
               // Indicates communication with the service was successful.
               // Identify any detected threats.
               if (sbResponse.getDetectedThreats().isEmpty()) {
                   // No threats found.
               } else {
                   // Threats found!
               }
        }
   })
   .addOnFailureListener(this, new OnFailureListener() {
           @Override
           public void onFailure(@NonNull Exception e) {
               // An error occurred while communicating with the service.
               if (e instanceof ApiException) {
                   // An error with the Google Play Services API contains some
                   // additional details.
                   ApiException apiException = (ApiException) e;
                   Log.d(TAG, "Error: " + CommonStatusCodes
                       .getStatusCodeString(apiException.getStatusCode()));

                   // Note: If the status code, apiException.getStatusCode(),
                   // is SafetyNetStatusCode.SAFE_BROWSING_API_NOT_INITIALIZED,
                   // you need to call initSafeBrowsing(). It means either you
                   // haven't called initSafeBrowsing() before or that it needs
                   // to be called again due to an internal error.
               } else {
                   // A different, unknown type of error occurred.
                   Log.d(TAG, "Error: " + e.getMessage());
               }
           }
   });

قراءة رد التحقق من عنوان URL

باستخدام الكائن SafetyNetApi.SafeBrowsingResponse الذي تم عرضه، استدعِ طريقة getDetectedThreats() التي تعرض قائمة بالكائنات SafeBrowsingThreat. وإذا كانت القائمة المعروضة فارغة، هذا يعني أن واجهة برمجة التطبيقات لم ترصد أي تهديدات معروفة. إذا لم تكن القائمة فارغة، يمكنك استدعاء getThreatType() في كل عنصر في القائمة لتحديد التهديدات المعروفة التي رصدتها واجهة برمجة التطبيقات.

لمعرفة لغة التحذير المقترَحة، راجِع دليل مطوِّري واجهة برمجة التطبيقات للتصفُّح الآمن.

تحديد أنواع التهديد التي تهمك

تحتوي الثوابت في الفئة SafeBrowsingThreat على أنواع التهديدات المتوافقة حاليًا:

عند استخدام واجهة برمجة التطبيقات، يمكنك إضافة ثوابت نوع التهديد كوسيطات. يمكنك إضافة العديد من الثوابت الخاصة بنوع التهديد التي يتطلبها تطبيقك، ولكن يمكنك فقط استخدام الثوابت التي لم يتم وضع علامة عليها على أنها متوقفة.

إيقاف جلسة "التصفّح الآمن"

إذا لم يكن تطبيقك بحاجة إلى استخدام واجهة برمجة تطبيقات "التصفّح الآمن" لفترة طويلة، تحقَّق من جميع عناوين URL اللازمة داخل تطبيقك ثم أوقِف جلسة "التصفّح الآمن" باستخدام الطريقة shutdownSafeBrowsing():

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

ننصحك باستدعاء shutdownSafeBrowsing() باستخدام طريقة نشاطك onPause() واستدعاء initSafeBrowsing() باستخدام طريقة onResume() في نشاطك. ومع ذلك، تأكَّد من انتهاء تنفيذ initSafeBrowsing() قبل طلب lookupUri(). من خلال التأكد من أن جلستك دائمًا جديدة، يمكنك تقليل احتمالية حدوث أخطاء داخلية في تطبيقك.

البيانات التي تجمعها واجهة برمجة تطبيقات SafetyNet للتصفح الآمن

تجمع واجهة برمجة تطبيقات SafetyNet للتصفح الآمن البيانات التالية تلقائيًا عند اتصالها بخدمة التصفح الآمن على Android:

نسعى إلى الالتزام بالشفافية قدر الإمكان، إلا أنّك وحدك المسؤول عن تحديد كيفية الاستجابة لنموذج قسم "أمان البيانات" على Google Play بشأن ممارسات جمع بيانات المستخدمين ومشاركتها والحفاظ على أمانها في تطبيقك.