הגדרת פרויקט 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

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

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

  • בתיקייה Gradle Scripts, פותחים את הקובץ 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 לצורך פיתוח.
    • מצמצמים את מספר התרגומים לשפות שנכללים בגרסת ה-build: מגדירים את resConfigs לשפה אחת במהלך הפיתוח. בגרסה הסופית, צריך להגדיר את resConfigs לשפות שבהן משתמשים בפועל. כברירת מחדל, Gradle כולל מחרוזות של משאבים לכל השפות שנתמכות על ידי Navigation SDK.

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

    • אם אתם מפתחים את האפליקציה באמצעות פלאגין של Android Gradle מגרסה 4.0.0 ואילך, התוסף מרחיב את התמיכה בשימוש במספר ממשקי API של שפת Java 8. מידע נוסף זמין במאמר בנושא תמיכה ב-desugaring ב-Java 8. אפשר לעיין בקטע הקוד לדוגמה של סקריפט הבנייה שבהמשך כדי לראות איך משתמשים באפשרויות של קומפילציה ותלות.
    • ב-Android מגרסה 7.3.0 ואילך, צריך להשתמש ב-Gradle 8.11.1, ב-Android Gradle plugin מגרסה 8.10.0 ובספריית Desugar‏ com.android.tools:desugar_jdk_libs_nio:2.0.3.
    • צריך להפעיל את ספריית ה-Desugar עבור מודול app וכל מודול שתלוי ישירות ב-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.0.3'
}

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

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

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

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

  • NOTICE.txt
  • LICENSES.txt

אם אתם לקוחות של Mobility או Fleet Engine Deliveries

לקוחות של Mobility או של Fleet Engine Deliveries יכולים לקרוא על החיוב במסמכי התיעוד של Mobility. מידע נוסף על תיעוד עסקאות זמין במאמרים הגדרת חיוב, תיעוד עסקאות שניתן לחייב עליהן, דיווח ותיעוד עסקאות שניתן לחייב עליהן (Android).