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

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

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

يقدّم الإصدار 5 (الإصدار v5) الجديد تحسينات كبيرة في ما يتعلّق بحداثة البيانات والخصوصية من خلال استخدام بروتوكول HTTP غير الواعي.

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

بنود الخدمة

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

طلب مفتاح Android API وتسجيله

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

في الإصدار v5، عليك تقديم مفتاح واجهة برمجة التطبيقات هذا عند إنشاء مثيل SafeBrowsingClient.

إضافة تبعية SafetyNet API

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

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

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

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

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

في الإصدار v5، يقدّم GmsCore برنامج التصفح الآمن للعميل. عليك الحصول على مثيل SafeBrowsingClient. لقد بسّطنا واجهة برمجة التطبيقات لزيادة الكفاءة وتقليل حجمها.

// Draft interface for the new client
public interface SafeBrowsingClient extends HasApiKey<SafeBrowsingApiOptions> {
  Task<SafeBrowsingResponse> lookupUri(String uri, @ThreatType List<Integer> threatTypes, @Protocol int protocol);
  Task<SupportedThreatTypesResponse> getSupportedThreatTypes();
}

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

استخدِم طريقة lookupUri لمعرفة ما إذا كان معرّف URI يمثّل تهديدًا. عليك تحديد البروتوكول المقصود، الذي يمكن أن يكون القائمة المحلية المحظورة (الإصدار v4) أو الحماية في الوقت الفعلي (الإصدار v5) .

إرسال طلب فحص عنوان 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());
               }
           }
   });

تأخذ توقيع lookupUri المعدَّل معرّف URI وقائمة بأنواع التهديدات والبروتوكول.

val threatTypes = listOf(ThreatType.TYPE_SOCIAL_ENGINEERING, ThreatType.TYPE_MALWARE)
val protocol = Protocol.REAL_TIME // or Protocol.LOCAL_BLOCK_LIST

safeBrowsingClient.lookupUri(url, threatTypes, protocol)
    .addOnSuccessListener { response ->
        if (response.detectedThreats.isEmpty()) {
            // No threats found
        } else {
            // Threats detected!
        }
    }

قراءة الردّ على طلب فحص عنوان URL

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

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

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

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

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

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

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

SafetyNet.getClient(this).shutdownSafeBrowsing()

SafetyNet.getClient(this).shutdownSafeBrowsing();

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

تفاصيل الحماية في الوقت الفعلي

يقدّم الإصدار v5 وضع الحماية في الوقت الفعلي الذي يتجنّب مشاكل عدم حداثة البيانات (التي يمكن أن تصل إلى 20 إلى 50 دقيقة في الإصدار v4). يتحوّل هذا الوضع من بروتوكول السماح تلقائيًا إلى بروتوكول الفحص تلقائيًا ، ما يعزّز الحماية من التهديدات التي تنتشر بسرعة. في وضع الوقت الفعلي، تحتفظ برامج العملاء بقاعدة بيانات محلية وذاكرة تخزين مؤقت عالمية للمواقع الإلكترونية التي يُرجّح أن تكون غير ضارة لتوفير حماية في الوقت الفعلي تقريبًا باستخدام أحدث بيانات التهديدات.

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

تتيح لك واجهة برمجة التطبيقات اختيار أنواع التهديدات المهمة لاحتياجاتك. تتيح واجهة برمجة التطبيقات v5 نطاقًا أوسع من أنواع التهديدات:

البيانات التي تجمعها SafetyNet Safe Browsing API

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

تجمع SafetyNet Safe Browsing API بادئة التجزئة لعناوين URL لرصد عناوين URL الضارة. ويستخدم الإصدار 5 بروتوكول HTTP غير الواعي لزيادة حماية بيانات المستخدم أثناء عمليات البحث هذه.

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