הצטרפו אלינו לאירוע הבא של Google Maps Platform Developer Community Day בסן פרנסיסקו בדצמבר. להגשת בקשה להשתתפות.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

מוסיפים את התלות הבאה להגדרות של 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>
הערה: אם אתם לקוחות של Mobility Services שמשדרגים ממאגר Maven הפרטי המקורי, שימו לב ששמות הקבוצות והפריטים השתנו, ואין יותר צורך בפלאגין com.google.cloud.artifactregistry.gradle-plugin.

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

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 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.
הוספת תהליך הסרה של סוכר תחבירי לתמיכה ב-Java8
- אם אתם מפתחים את האפליקציה באמצעות הפלאגין של Android Gradle בגרסה 4.0.0 ואילך, הפלאגין מרחיב את התמיכה בשימוש בכמה ממשקי API של שפת Java 8. מידע נוסף זמין במאמר תמיכה בהסרה של סוכר תחבירי ב-Java 8. בקטע הקוד לדוגמה של סקריפט ה-build שבהמשך מוסבר איך להגדיר את אפשרויות הקימפול והתלות.
- השתמשו בגרסאות של Gradle, של הפלאגין של Android Gradle ‏ (AGP) ושל ספריית Desugar שתואמות לגרסה של Navigation SDK. הנה טבלה לדוגמה:
- צריך להפעיל את ספריית Desugar במודול app ובכל מודול שתלוי ישירות ב-Navigation SDK.

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

גרסת Navigation SDK	גרסת Gradle	גרסת AGP	ספריית Desugar
‫8.0.0 ומעלה	9.1.0	9.0.1	`com.android.tools:desugar_jdk_libs_nio:2.1.5`
‫7.7.0 עד 7.9.0	8.13	8.13.2	`com.android.tools:desugar_jdk_libs_nio:2.1.5`
‫7.3.0 עד 7.6.0	8.11.1	8.10.0	`com.android.tools:desugar_jdk_libs_nio:2.0.3`

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

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

כדי להתקין את Secrets Gradle Plugin for Android ולשמור את מפתח ה-API:

ב-Android Studio, פותחים את הקובץ build.gradle.kts או build.gradle ברמה העליונה ומוסיפים את הקוד הבא לבלוק plugins.

Kotlin

plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

Groovy

plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}

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

Kotlin

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

Groovy

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

אם אתם משתמשים ב-Android Studio, סנכרנו את הפרויקט עם Gradle.
פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API שלכם. חשוב להוסיף את secrets.properties לקובץ .gitignore (או להחריג אותו בדרך אחרת ממערכת ניהול הגרסאות) כדי לא להכניס את מפתח ה-API לניהול הגרסאות.
הערה: אם הקובץ secrets.properties לא קיים, צריך ליצור אותו באותה תיקייה שבה נמצא הקובץ local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
יוצרים את הקובץ local.defaults.properties בספרייה ברמה העליונה, באותה תיקייה שבה נמצא הקובץ secrets.properties, ואז מוסיפים את הקוד הבא.

הערה: צריך להזין את הקוד בדיוק כמו שהוא מופיע. אל תחליפו את הערך DEFAULT_API_KEY במפתח ה-API שלכם.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
המטרה של הקובץ הזה היא לספק מיקום גיבוי למפתח ה-API אם הקובץ secrets.properties לא נמצא, כדי שה-builds לא ייכשלו. זה יכול לקרות אם משכפלים את האפליקציה ממערכת בקרת גרסאות שמשמיטה את secrets.properties, ועדיין לא יוצרים קובץ secrets.properties באופן מקומי כדי לספק את מפתח ה-API.
אפשר להוסיף את מפתח ה-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. השם הקודם הזה מאפשר אימות רק ל-Android Maps API v2. אפליקציה יכולה לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם שניהם צוינו, ה-API יקפיץ הודעת שגיאה.
- מציינים את מפתח ה-API באופן פרוגרמטי:
  הפלאגין Secrets Gradle הופך את המפתח לזמין בכיתה BuildConfig. באתחול של האפליקציה (לדוגמה, ב-method Application.onCreate()), מפעילים את ה-method באופן הבא:
  Kotlin
  1. מוסיפים את הצהרות הייבוא הבאות:
    import com.google.android.libraries.navigation.NavigationApi
  2. מוסיפים את הקוד הבא ל-method‏ Application.onCreate():
    NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)
  Java
  1. מוסיפים את הצהרות הייבוא הבאות:
    import com.google.android.libraries.navigation.NavigationApi;
  2. מוסיפים את הקוד הבא ל-method‏ Application.onCreate():
    NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
  הערה: כשמשתמשים ב-setApiKey(), חשוב לזכור:
  - צריך לספק מפתח API שאינו ריק או null.
  - צריך להפעיל את setApiKey() רק פעם אחת במהלך חיי האפליקציה. ה-method מחזירה IllegalStateException אם קוראים לה יותר מפעם אחת.
  - מפעילים את setApiKey() לפני שמפעילים רכיבים אחרים של Navigation SDK, כמו Navigator.
  - המפתח שאתם מספקים בשיטה הזו מבטל כל מפתח API ב-AndroidManifest.xml.
  - צריך להשתמש ב-Navigation SDK בגרסה 7.6 ואילך.

ב-Android Studio, פותחים את הקובץ build.gradle.kts או build.gradle ברמת המודול ועורכים את המאפיין secrets. אם המאפיין secrets לא קיים, מוסיפים אותו.

עורכים את המאפיינים של הפלאגין כדי להגדיר את propertiesFileName לערך "secrets.properties", את defaultPropertiesFileName לערך "local.defaults.properties", ומגדירים מאפיינים אחרים.

Kotlin

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

Groovy

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
    // 2. Add this line, where YOUR_API_KEY is your API key:
    //        MAPS_API_KEY=YOUR_API_KEY
    propertiesFileName = "secrets.properties"

    // A properties file containing default secret values. This file can be
    // checked in version control.
    defaultPropertiesFileName = "local.defaults.properties"
}

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

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

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

NOTICE.txt
LICENSES.txt

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

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

תלויות ידניות (לא Gradle או Maven)

אם מערכת ה-build שלכם לא פותרת יחסי תלות טרנזיטיביים (כמו Bazel), או אם אתם משלבים את ה-AAR באופן ידני, אתם צריכים להוסיף את יחסי התלות האלה לפרויקט. ‫Gradle ו-Maven פותרים אותן באופן אוטומטי.

androidx.datastore:datastore-core
androidx.datastore:datastore-guava
com.google.guava:listenablefuture
androidx.concurrent:concurrent-futures

הגדרת פרויקט Android Studio קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

Gradle

Maven

Gradle

Maven

הגדרת ה-build

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

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

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

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Java

Kotlin

Groovy

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

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

תלויות ידניות (לא Gradle או Maven)

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