איך משתמשים ב-App Check כדי לאבטח את Navigation SDK ל-Android

Firebase App Check מספקת הגנה על קריאות מהאפליקציה שלכם ל-Google Maps Platform, על ידי חסימת תעבורת נתונים שמגיעה ממקורות שאינם האפליקציות הלגיטימיות שלכם. כדי לעשות את זה, הוא מבקש הערכה של האותנטיות של האפליקציה או המכשיר מספק אישורים כמו Play Integrity. כשמשלבים את האפליקציה עם App Check, מוסיפים הגנה מפני בקשות זדוניות ולא מורשות, וכך מגינים על החיוב מפני חיובים לא מורשים. בנוסף, App Check משפר באופן משמעותי את הדיווח בזמן אמת על שיבושים בסביבת האפליקציות של Fleet, וכך מועילה לכל הנהגים שמשתמשים באפליקציה. מידע נוסף זמין במאמר דיווח על שיבושים.

חשוב: כברירת מחדל, App Check לא חוסם תנועה לא מורשית. צריך להפעיל את האכיפה באופן ידני אחרי שמאמתים את מדדי האפליקציה (ראו שלב 6: מעקב אחרי הבקשות של האפליקציה והחלטה לגבי אכיפה).

למה כדאי להשתמש ב-App Check?

‫App Check מגן על שני אזורים נפרדים ב-Navigation SDK ל-Android: פונקציונליות הניווט הראשית ודיווח על שיבושים.

ניווט

‫App Check עוזר לחסום בקשות עיקריות של Navigation SDK ל-Android ממקורות זדוניים או לא מורשים. הפעולה הזו מגינה על הפרויקט שלכם מפני הונאות חיובים וניצול המכסות, ומועילה לכם באופן ישיר.

דיווח על שיבושים

מומלץ מאוד להשתמש ב-App Check אם האפליקציה שלכם תומכת בדיווח על שיבושים בזמן אמת וביכולות הצבעה. הפעלת App Check מבטיחה שהנהגים יקבלו את המסלולים המדויקים ביותר, תוך התחשבות בכל המשוב בזמן אמת.

למה App Check חשוב לדיווח:

• רף האמינות הגבוה של חסימות: אירועים שמשפיעים על המסלול, כמו חסימות כבישים, יכולים לשנות באופן משמעותי את התנהגות הניתוב של כל הנהגים. כדי להגן על המפה מפני ונדליזם, ספאם או דיווחים לא מדויקים, תשתית הניהול של Google לשיבושים שקשורים לחסימות כבישים מסתמכת על אותות חזקים של תקינות המכשיר ותקינות האפליקציה.
• איך App Check מאמת דיווחים: דיווחים והצבעות של משתמשים שנשלחים מ-Navigation SDK ל-Android כוללים את האסימון של App Check. הקצה העורפי של Google משתמש באסימון הזה כדי לאמת את הלגיטימיות של המשוב, להעלות את רמת האמינות שלו ולאפשר להעריך את ההשפעה שלו על המפה בזמן אמת.
• ההשפעה של השמטת App Check: דוחות שנשלחים בלי אסימון App Check תקף נבדקים לפי מודל של רמת אמון נמוכה יותר, ויכול להיות שהם יעובדו רק כאותות שקטים. המשמעות היא שהמשתמשים עדיין יכולים לדווח ולהצביע, אבל יש פחות סיכוי שהדיווחים שלהם יופיעו במפה או ישפיעו על המסלולים של נהגים אחרים, והם יצטרכו אימות נוסף.

האם App Check מתאים לי?

ברוב המקרים מומלץ להשתמש ב-App Check, אבל אין צורך ב-App Check או שהיא לא נתמכת בתרחישים הבאים:

• אפליקציות פרטיות או ניסיוניות: אם האפליקציה לא נגישה לכולם, אין צורך ב-App Check.
• מכשירים שנפרצו: ספקי האימות המומלצים מונעים את ההפעלה של Navigation SDK ל-Android במכשירים לא מהימנים, כמו טלפונים שעברו פריצה (root או jailbreak). כדי לתמוך במכשירים האלה, צריך לפרוס ספק אישורים בהתאמה אישית.
• מכשירי Android ללא GMS: במכשירי Android צריכה לפעול חבילת שירותי Google לנייד‏ (GMS) כדי להשתמש ב-Play Integrity. אם אתם מתכננים לתמוך במכשירי Android שאינם GMS, אתם צריכים לפרוס ספק אימות בהתאמה אישית.

סקירה כללית של שלבי ההטמעה

ככלל, אלה השלבים לשילוב האפליקציה עם App Check:

1. מוסיפים את Firebase לאפליקציה.
2. מוסיפים את הספרייה של App Check ומפעילים את App Check.
3. מוסיפים ספק אסימונים. בשלב הזה, ספק האימות שבחרתם נקרא לאמת את תקינות המכשיר או האפליקציה.
4. מפעילים את Navigation API ואת App Check API.
5. מפעילים את ניפוי הבאגים. האפשרות הזו שימושית במהלך הפיתוח או בסביבות של שילוב רציף (CI).
6. לפני שמפעילים את האכיפה, כדאי לעקוב אחרי הבקשות של האפליקציה. כך תוכלו לאכוף את App Check בצורה חלקה בלי להפריע למשתמשים.

שיקולים בתכנון שילוב של App Check

• מכסות של ספק האימות: לספק האימות שאנחנו ממליצים עליו, Play Integrity, יש מגבלת קריאות יומית ברמת השימוש הרגילה ב-API. מידע נוסף על מגבלות הקריאות זמין בדף הגדרה במאמרי העזרה למפתחים של Google Play Integrity.
• זמן אחזור בהפעלה: ברוב המקרים, המשתמשים לא יחוו זמן אחזור במהלך שימוש רגיל, כי אסימוני App Check נשמרים במטמון במכשיר. כדי לשמור על ביצועים חלקים, המערכת מרעננת באופן אוטומטי את אסימוני App Check ברקע לפני שהתוקף שלהם פג. עם זאת, אם אין אסימון App Check תקין, המשתמשים באפליקציה יחוו עיכוב מסוים בהפעלה. לדוגמה, זמן האחזור הזה מתרחש במהלך הפעלות במצב התחלתי (cold start) כשהאסימון שנשמר במטמון חסר או שפג תוקפו.
• אורך החיים (TTL) של האסימון: משך הזמן שבו האסימון של App Check תקף לפני שצריך לרענן אותו. אפשר להגדיר את משך הזמן הזה במסוף Firebase, מ-30 דקות ועד 7 ימים. מומלץ להגדיר משך זמן של שעה כבסיס מאובטח, אבל ה-SDK מנסה באופן אוטומטי לבצע רענון ברקע בערך במחצית ממשך הזמן של ה-TTL. הוראות מפורטות לגבי המסוף זמינות במסמכי התיעוד של Firebase App Check.

שילוב האפליקציה עם App Check

דרישות מוקדמות ודרישות סף

• אפליקציה שמותקנת בה גרסה 7.9 ומעלה של Navigation SDK ל-Android.
• טביעת האצבע לאישור SHA-256 של האפליקציה.
• שם החבילה של האפליקציה.
• אתם צריכים להיות הבעלים של האפליקציה במסוף Google Cloud.
• מזהה הפרויקט של האפליקציה ממסוף Google Cloud.

שלב 1: מוסיפים את Firebase לאפליקציה

כדי להוסיף את Firebase לאפליקציה, פועלים לפי ההוראות במסמכי התיעוד למפתחים של Firebase. מוסיפים את הקובץ google-services.json לספרייה ברמת האפליקציה של הפרויקט.

שלב 2: מוסיפים את הספרייה של App Check ומפעילים את App Check

מוסיפים את התלות של App Check לקובץ build.gradle של האפליקציה:

‫Groovy‏ (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

מפעילים את App Check במחלקת האפליקציה או בפעילות הראשית:

Java

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

שלב 3: מוסיפים את ספק הטוקנים

הערה: אם באפליקציה שלכם נעשה שימוש גם בערכות SDK אחרות של Google Maps Platform שתומכות ב-App Check (כמו Places SDK), אתם יכולים להשתמש באותה הגדרה של Firebase App Check, אבל אתם צריכים להטמיע ולרשום את ממשק ספק הטוקנים הספציפי לכל SDK.

יוצרים הטמעה של הממשק MapsAppCheckTokenProvider. הספק הזה מאחזר באופן אסינכרוני אסימונים של App Check מ-Firebase App Check ומעביר אותם למקבץ הרשת (network stack) של Navigation SDK ל-Android באמצעות MapsAppCheckTokenCallback:

Java

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

שלב 4: מפעילים את Navigation API ואת App Check API

מפעילים את Navigation SDK ל-Android ורושמים את המכונה של ספק הטוקנים המאוחד באמצעות MapsApiSettings.setAppCheckTokenProvider():

Java

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

שלב 5: הפעלת ניפוי באגים (אופציונלי)

אחרי שתאכפו את App Check ב-Navigation SDK ל-Android, התכונות של האפליקציה שתלויות ב-Navigation SDK ל-Android לא יפעלו בסימולטור או בסביבת שילוב רציף (CI), כי הסביבות האלה לא נחשבות למכשירים תקינים. כדי להריץ את האפליקציה בסביבות האלה במהלך הפיתוח והבדיקה, צריך ליצור גרסת build לניפוי באגים של האפליקציה שמשתמשת בספק אימות לצורכי ניפוי באגים של App Check במקום בספק אימות בסביבת הייצור.

1. מוסיפים את התלות של ספק אימות לצורכי ניפוי באגים לקובץ build.gradle של האפליקציה:

   ‫Groovy‏ (build.gradle)

   dependencies {
       implementation 'com.google.firebase:firebase-appcheck-debug'
   }

2. מגדירים את App Check כך שישתמש ב-debug provider factory בגרסאות ה-build לניפוי באגים:

   Java

   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;
   
   if (BuildConfig.DEBUG) {
       firebaseAppCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       );
   } else {
       firebaseAppCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance()
       );
   }

   Kotlin

   import com.google.firebase.Firebase
   import com.google.firebase.appcheck.appCheck
   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
   
   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance(),
       )
   } else {
       Firebase.appCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance(),
       )
   }

3. מפעילים את האפליקציה באמולטור או במכשיר לניפוי באגים. ‫App Check ידפיס אסימון ניפוי באגים מקומי לפלט של logcat.
4. מעתיקים את אסימון ניפוי הבאגים הזה ורושמים אותו במסוף Firebase. פרטים נוספים זמינים במסמכי התיעוד של ספק אימות לצורכי ניפוי באגים של Firebase App Check.

שלב 6: מעקב אחרי הבקשות לאפליקציות וקבלת החלטה לגבי אכיפה

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

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

1. כדי לראות את אחוז התנועה המאומתת לעומת התנועה הלא מאומתת, נכנסים למסך המדדים של App Check במסוף Firebase.
2. אחרי שמוודאים שרוב התנועה מאומתת ושהמשתמשים הלגיטימיים עדכנו לגרסה של האפליקציה שכוללת את ההטמעה של App Check, מפעילים את האכיפה.
3. אחרי שתפעילו את האכיפה, App Check ידחה את כל התנועה שלא כוללת אסימון App Check תקין.