ממשק API לגלישה בטוחה של SafetyNet

SafetyNet Safebrowsing API, ספרייה שמופעלת על ידי Google Play Services, מספק שירותים שמאפשרים לקבוע אם כתובת URL סומנה כאיום ידוע על ידי Google.

האפליקציה שלכם יכולה להשתמש ב-API הזה כדי לקבוע אם כתובת URL מסוימת סווגה על ידי Google כאיום ידוע. באופן פנימי, SafetyNet מטמיע לקוח לפרוטוקול הרשת של הגלישה הבטוחה בגרסה 4 שפותח על ידי Google. גם קוד הלקוח וגם פרוטוקול הרשת בגרסה 4 תוכננו כדי לשמור על פרטיות המשתמשים ולצמצם את צריכת הסוללה ואת רוחב הפס. אפשר להשתמש ב-API הזה כדי לנצל את מלוא היתרונות של שירות הגלישה הבטוחה של Google ב-Android בצורה הכי יעילה מבחינת משאבים, בלי להטמיע את פרוטוקול הרשת שלו.

במסמך הזה מוסבר איך להשתמש ב-SafetyNet Safe Browsing Lookup API כדי לבדוק אם כתובת URL מסוימת מכילה איומים ידועים.

תנאים והגבלות

השימוש ב-Safe Browsing API מבטא את הסכמתכם לתנאים ולהגבלות. לפני שמשתמשים ב-Safe Browsing API, צריך לקרוא ולהבין את כל התנאים וההגבלות ותנאי המדיניות החלים.

בקשה ורישום של מפתח Android API

לפני שמשתמשים ב-Safe Browsing API, צריך ליצור ולרשום מפתח API ל-Android. להוראות ספציפיות, ראו תחילת העבודה עם גלישה בטוחה.

הוספת התלות ב-SafetyNet API

לפני שמשתמשים ב-Safe Browsing API, צריך להוסיף את SafetyNet API לפרויקט. אם משתמשים ב-Android Studio, צריך להוסיף את התלות הזאת לקובץ Gradle ברמת האפליקציה. מידע נוסף זמין במאמר הגנה מפני איומי אבטחה באמצעות SafetyNet.

איך מפעילים את ה-API

כדי להשתמש ב-Safe Browsing API, צריך לאתחל את ה-API באמצעות קריאה ל-initSafeBrowsing() ולהמתין להשלמתה. קטע הקוד הבא הוא דוגמה לכך:

Kotlin

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

Java

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

הערה: כדי למזער את ההשפעה של האיניציאליזציה של האפליקציה, צריך להפעיל את initSafeBrowsing() בהקדם האפשרי ב-method‏ onResume() של הפעילות.

שליחת בקשה לבדיקת כתובת URL

האפליקציה יכולה להשתמש בבדיקת כתובות URL כדי לקבוע אם כתובת URL מסוימת מהווה איום ידוע. יכול להיות שחלק מסוגי האיומים לא יעניינו את האפליקציה שלכם, כי באמצעות ה-API תוכלו לבחור אילו סוגי איומים חשובים לצרכים שלכם. אפשר לציין כמה סוגים של איומים ידועים.

שליחת הבקשה לבדיקת כתובת ה-URL

ה-API לא תלוי בסכימה שבה משתמשים, כך שאפשר להעביר את כתובת ה-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. אם הרשימה שחוזרת ריקה, ה-API לא זיהה איומים ידועים. אם הרשימה לא ריקה, צריך להפעיל את getThreatType() לכל רכיב ברשימה כדי לקבוע אילו איומים ידועים זוהו על ידי ה-API.

כדי לראות הצעות לשפת האזהרה, ראו מדריך למפתחים בנושא גלישה בטוחה בממשק API.

ציון סוגי עניין של איומים

הקבועים בכיתה SafeBrowsingThreat מכילים את סוגי האיומים הנתמכים כרגע:

סוג האיום	הגדרה
TYPE_POTENTIALLY_HARMFUL_APPLICATION	סוג האיום הזה מזהה כתובות URL של דפים שסומנו כמכילות אפליקציות שעלולות להזיק.
TYPE_SOCIAL_ENGINEERING	סוג האיום הזה מזהה כתובות URL של דפים שסומנו כמכילים איומי הנדסה חברתית.

כשמשתמשים ב-API, מוסיפים ערכי קבוע של סוג האיום כארגומנטים. אפשר להוסיף כמה קבועים של סוגי איומים שרוצים באפליקציה, אבל אפשר להשתמש רק בקבועים שלא מסומנים כמיושנים.

השבתת הסשן של הגלישה הבטוחה

אם לאפליקציה שלכם אין צורך להשתמש ב-Safe Browsing API למשך זמן ממושך, כדאי לבדוק את כל כתובות ה-URL הנדרשות באפליקציה ולאחר מכן לסגור את הסשן של Safe Browsing באמצעות השיטה shutdownSafeBrowsing():

Kotlin

SafetyNet.getClient(this).shutdownSafeBrowsing()

Java

SafetyNet.getClient(this).shutdownSafeBrowsing();

מומלץ לקרוא ל-shutdownSafeBrowsing() בשיטה onPause() של הפעילות, ולקרוא ל-initSafeBrowsing() בשיטה onResume() של הפעילות. עם זאת, חשוב לוודא שהפעלת initSafeBrowsing() הסתיימה לפני שמפעילים את lookupUri(). אם תדאגו שהסשן תמיד יהיה עדכני, תוכלו לצמצם את הסיכוי לשגיאות פנימיות באפליקציה.

נתונים שנאספים על ידי SafetyNet Safe Browsing API

כש-SafetyNet Safe Browsing API מתקשר עם שירות הגלישה הבטוחה ב-Android, הוא אוסף באופן אוטומטי את הנתונים הבאים:

נתונים	תיאור
פעילות באפליקציות	איסוף קידומת גיבוב של כתובות URL אחרי התאמת קידומת של גיבוב מקומי למטרות זיהוי כתובות URL זדוניות.

אנחנו משתדלים לשמור על שקיפות רבה ככל האפשר, אבל באחריותך הבלעדית להחליט איך להגיב לטופס של סעיף אבטחת הנתונים של Google Play בנוגע לאיסוף נתוני המשתמשים, לשיתוף שלהם ולנוהלי האבטחה באפליקציה.