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

واجهة برمجة التطبيقات SafetyNet Safe Browsing API هي مكتبة مستندة إلى خدمات Google Play، وتقدّم خدمات لتحديد ما إذا كانت Google قد وضعت علامة على عنوان URL تشير إلى أنّه تهديد معروف.

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

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

بنود الخدمة

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

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

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

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

Kotlin

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

Java

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

و

Kotlin

var url = "www.google.com"

Java

String url = "www.google.com";

صالحة

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

Kotlin

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

Java

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() على كل عنصر في القائمة لتحديد التهديدات المعروفة التي رصدتها واجهة برمجة التطبيقات.

للاطّلاع على لغة التحذير المقترَحة، يُرجى الاطّلاع على دليل مطوّري واجهة برمجة التطبيقات Safe Browsing API.

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

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

نوع التهديد التعريف
TYPE_POTENTIALLY_HARMFUL_APPLICATION يحدِّد هذا النوع من التهديدات عناوين URL للصفحات التي تم الإبلاغ عنها على أنّها تحتوي على تطبيقات قد تتسبّب بضرر.
TYPE_SOCIAL_ENGINEERING يحدِّد نوع التهديد هذا عناوين URL للصفحات التي تم الإبلاغ عنها على أنّها تحتوي على تهديدات الهندسة الاجتماعية.

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

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

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

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

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

البيانات التي تجمعها واجهة برمجة التطبيقات SafetyNet Safe Browsing API

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

البيانات الوصف
نشاط التطبيق تجمع هذه السمة بادئة التجزئة لعناوين URL بعد تطابق بادئة التجزئة المحلية بغرض رصد عناوين URL الضارة.

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