הגדרת פרויקט Android Studio

בדף הזה מוסבר איך לשלב את Navigation SDK בפרויקט הפיתוח.

הוספה של Navigation SDK לפרויקט

‫Navigation SDK זמין דרך Google Maven Repository. אפשר להוסיף את ה-SDK לפרויקט באמצעות ההגדרה של Gradle build.gradle או של Maven pom.xml.

1. מוסיפים את התלות הבאה להגדרות של Gradle או Maven, ומחליפים את ה-placeholder ‏VERSION_NUMBER בגרסה הרצויה של Navigation SDK ל-Android.

   Gradle

   מוסיפים את הקוד הבא לקובץ build.gradle ברמת המודול:

   dependencies {
           ...
           implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
   }
   

   Maven

   מוסיפים את הנתונים הבאים אל pom.xml:

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

2. אם יש לכם תלויות שמשתמשות ב-Maps SDK, אתם צריכים להחריג את התלות בכל תלות מוצהרת שמסתמכת על Maps SDK.

   Gradle

   מוסיפים את השורות הבאות לbuild.gradle ברמה העליונה:

   allprojects {
           ...
           // Required: you must exclude the Google Play service Maps SDK from
           // your transitive dependencies to make sure there won't be
           // multiple copies of Google Maps SDK in your binary, as the Navigation
           // SDK already bundles the Google Maps SDK.
           configurations {
               implementation {
                   exclude group: 'com.google.android.gms', module: 'play-services-maps'
               }
           }
   }
   

   Maven

   מוסיפים את הנתונים הבאים אל pom.xml:

   <dependencies>
     <dependency>
     <groupId>project.that.brings.in.maps</groupId>
     <artifactId>MapsConsumer</artifactId>
     <version>1.0</version>
       <exclusions>
         <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
         <exclusion>  <!-- declare the exclusion here -->
           <groupId>com.google.android.gms</groupId>
           <artifactId>play-services-maps</artifactId>
         </exclusion>
       </exclusions>
     </dependency>
   </dependencies>
   

הגדרת ה-build

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

עדכון מאפיינים מקומיים

• בתיקיית סקריפטים של Gradle, פותחים את הקובץ local.properties ומוסיפים את השורה android.useDeprecatedNdk=true.

עדכון סקריפט ה-build של Gradle

• פותחים את הקובץ build.gradle (Module:app) ופועלים לפי ההנחיות הבאות כדי לעדכן את ההגדרות בהתאם לדרישות של Navigation SDK. כדאי גם להגדיר את אפשרויות האופטימיזציה.

  הגדרות נדרשות ל-Navigation SDK

  1. מגדירים את minSdkVersion ל-24 ומעלה.
  2. מגדירים את הערך targetSdkVersion ל-36 ומעלה.
  3. מוסיפים dexOptions הגדרה שמגדילה את javaMaxHeapSize.
  4. הגדרת המיקום של ספריות נוספות.
  5. מוסיפים את repositories ו-dependencies ל-Navigation SDK.
  6. מחליפים את מספרי הגרסאות בתלות בגרסאות העדכניות ביותר שזמינות.

  הגדרות אופציונליות לקיצור משך זמן של תהליך build

  • מפעילים צמצום קוד וצמצום משאבים באמצעות R8/ProGuard כדי להסיר קוד ומשאבים שלא נמצאים בשימוש מיחסי תלות. אם השלב של R8/ProGuard נמשך יותר מדי זמן, כדאי להפעיל multidex לעבודת פיתוח.
  • מצמצמים את מספר התרגומים לשפות שנכללים בגרסה: מגדירים את הערך resConfigs לשפה אחת במהלך הפיתוח. בגרסת ה-build הסופית, מגדירים את resConfigs לשפות שבהן משתמשים בפועל. כברירת מחדל, Gradle כולל מחרוזות של משאבים לכל השפות שנתמכות על ידי Navigation SDK.

  הוספת desugaring לתמיכה ב-Java8

  • אם אתם יוצרים את האפליקציה באמצעות הפלאגין של Android Gradle בגרסה 4.0.0 ומעלה, הפלאגין מרחיב את התמיכה בשימוש במספר ממשקי API של שפת Java 8. מידע נוסף זמין במאמר בנושא תמיכה ב-desugaring ב-Java 8. בהמשך מופיע קטע קוד לדוגמה של סקריפט build שמראה איך להשתמש באפשרויות compile ו-dependency.
  • צריך להשתמש בגרסאות של Gradle, של פלאגין של Android Gradle ‏ (AGP) ושל ספריית Desugar שתואמות לגרסה של Navigation SDK. פרטים נוספים מופיעים בטבלה הבאה.
  • צריך להפעיל את ספריית Desugar עבור מודול app וכל מודול שתלוי ישירות ב-Navigation SDK.

בטבלה הבאה מפורטות הגרסאות של Gradle,‏ AGP וספריית Desugar שנדרשות לכל גרסה של Navigation SDK.

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

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

הוספת מפתח ה-API לאפליקציה

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

כדי לייעל את המשימה הזו, מומלץ להשתמש בפלאגין של Secrets Gradle ל-Android.

כדי להתקין את הפלאגין Secrets Gradle ל-Android ולאחסן את מפתח ה-API:

1. ב-Android Studio, פותחים את קובץ build.gradle ברמת הבסיס ומוסיפים את הקוד הבא לרכיב dependencies בקטע buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. פותחים את קובץ build.gradle ברמת האפליקציה ומוסיפים את הקוד הבא לרכיב plugins.

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. אם אתם משתמשים ב-Android Studio, סנכרנו את הפרויקט עם Gradle.
4. פותחים את הקובץ local.properties בספרייה ברמת הפרויקט, ואז מוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.

   MAPS_API_KEY=YOUR_API_KEY

5. אפשר להוסיף את מפתח ה-API לקובץ AndroidManifest.xml או לספק את מפתח ה-API באופן פרוגרמטי.
   • מוסיפים את מפתח ה-API אל AndroidManifest.xml:

     <meta-data
         android:name="com.google.android.geo.API_KEY"
         android:value="${MAPS_API_KEY}" />
             

     הערה: ‫com.google.android.geo.API_KEY הוא שם המטא-נתונים המומלץ למפתח ה-API. אפשר להשתמש במפתח עם השם הזה כדי לבצע אימות למספר ממשקי API שמבוססים על מפות Google בפלטפורמת Android, כולל Navigation SDK ל-Android. לצורך תאימות לדורות קודמים, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הזה הוא שם מדור קודם ומאפשר אימות רק לגרסה 2 של Android Maps API. אפליקציה יכולה לציין רק שם אחד של מטא-נתונים של מפתח API. אם מציינים את שניהם, ה-API יוצר חריגה.

   • העברת מפתח ה-API באופן פרוגרמטי:

     הפלאגין Secrets Gradle מאפשר להשתמש במפתח בכיתה BuildConfig. באתחול של האפליקציה (לדוגמה, בשיטה Application.onCreate()), קוראים לשיטה באופן הבא:

     Kotlin

     1. מוסיפים את הצהרות הייבוא הבאות:

        import com.google.android.libraries.navigation.NavigationApi

     2. מוסיפים את הקוד הבא לשיטה Application.onCreate():

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

     Java

     1. מוסיפים את הצהרות הייבוא הבאות:

        import com.google.android.libraries.navigation.NavigationApi;

     2. מוסיפים את הקוד הבא לשיטה Application.onCreate():

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);

     הערה: כשמשתמשים ב-setApiKey(), חשוב לזכור את הנקודות הבאות:

     • צריך לספק מפתח API שלא מכיל ערך null ושאינו ריק.
     • הפונקציה call setApiKey() מופעלת רק פעם אחת במהלך משך החיים של האפליקציה. השיטה יוצרת IllegalStateException אם קוראים לה יותר מפעם אחת.
     • צריך להתקשר אל setApiKey() לפני שמפעילים רכיבים אחרים של Navigation SDK, כמו Navigator.
     • המפתח שאתם מספקים באמצעות השיטה הזו מבטל כל מפתח API ב-AndroidManifest.xml.
     • משתמשים בגרסה 7.6 ואילך של Navigation SDK.

הוספת הקרדיטים הנדרשים לאפליקציה

אם אתם משתמשים ב-Navigation SDK for Android באפליקציה שלכם, אתם צריכים לכלול טקסט שיוך ורישיונות קוד פתוח כחלק מהקטע של ההודעות המשפטיות באפליקציה.

אפשר למצוא את טקסט לציון קרדיט הנדרש ואת רישיונות הקוד הפתוח בקובץ ה-ZIP של Navigation SDK ל-Android:

• NOTICE.txt
• LICENSES.txt