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

הגדרת הפרויקט – גרסה 4.99 וגרסאות קודמות

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

דרישות מינימליות לשימוש ב-Navigation SDK

הדרישות האלה חלות על Navigation SDK ל-Android בגרסה 4.99 ומגרסאות קודמות.

מסוף Google Cloud

פרויקט שמופעל בו Navigation SDK. כדי להקצות את השירות, פנו לנציג שלכם ב-Google Maps Platform.
האפליקציה שלך חייבת לטרגט לרמת API‏ 30 ומעלה.
כדי להפעיל אפליקציה שנבנתה באמצעות Navigation SDK, צריך להתקין ולהפעיל את Google Play Services במכשיר Android.
צריך להוסיף לאפליקציה טקסט של שיוכים ורישוי.

הגדרת הפרויקטים: פרויקט במסוף Cloud ופרויקט Android

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

כדי להגדיר

בדפדפן האינטרנט המועדף, נכנסים ל מסוף Cloud ויוצרים פרויקט במסוף Cloud.
בסביבת הפיתוח המשולבת (IDE), כמו Android Studio, יוצרים פרויקט פיתוח של אפליקציה ל-Android ורושמים את שם החבילה.
כדי לקבל גישה ל-Navigation SDK עבור פרויקט במסוף Cloud, צריך לפנות לנציג של Google Maps Platform.
במרכז הבקרה של מסוף Cloud בדפדפן האינטרנט, יוצרים פרטי כניסה כדי ליצור מפתח API עם הגבלות.
בדף מפתח ה-API, לוחצים על Android apps (אפליקציות ל-Android) באזור Application restrictions (הגבלות על אפליקציות).
לוחצים על Add the package name and fingerprint (הוספת שם החבילה וטביעת האצבע), ואז מזינים את שם החבילה של פרויקט הפיתוח ואת טביעת האצבע של מפתח SHA-1.
לוחצים על שמירה.

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

‫Navigation SDK זמין באמצעות Maven או כחבילת AAR. אחרי שיוצרים את פרויקט הפיתוח, אפשר לשלב בו את ה-SDK באחת מהדרכים הבאות.

שימוש ב-Maven לגרסה 4.5 ואילך של Navigation SDK (מומלץ)

בדוגמה הבאה נעשה שימוש במאגר Maven‏ google(), שהוא הדרך הפשוטה והמומלצת להוסיף את Navigation SDK לפרויקט

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

Gradle

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

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

אם משדרגים ממאגר Maven המקורי, חשוב לשים לב שהשמות של הקבוצה והארטיפקט השתנו, ושהפלאגין com.google.cloud.artifactregistry.gradle-plugin כבר לא נחוץ.

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

allprojects {
...
// Required: you must exclude the Google Play service Maps SDK from
// your transitive dependencies to make nsure 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>com.google.android.libraries.navigation</groupId>
     <artifactId>navigation</artifactId>
     <version>VERSION_NUMBER</version>
</dependency>
</dependencies>

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

<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>

שימוש ב-Maven ל-Navigation SDK בגרסה שלפני v4.5, או עם Driver SDK

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

מגדירים את הסביבה כדי לגשת למאגר Maven של Google כמו שמתואר בקטע דרישות מוקדמות במסמכי התיעוד של Consumer SDK. הגישה ל-Navigation SDK נשלטת באמצעות קבוצה במרחב העבודה.

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

Gradle

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

dependencies {
...
implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
}

מוסיפים את השורות הבאות ל-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>com.google.android.maps</groupId>
     <artifactId>navsdk</artifactId>
     <version>VERSION_NUMBER</version>
</dependency>
</dependencies>

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

<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>

שימוש בחבילת AAR שהורדה (לא מומלץ)

‫Navigation SDK זמין גם כחבילת AAR. אחרי שיוצרים את פרויקט הפיתוח, אפשר לשלב את ה-SDK. ההוראות האלה מניחות שאתם משתמשים ב-Android Studio כסביבת פיתוח משולבת (IDE).

מורידים את הגרסה העדכנית של Navigation SDK מGoogle Drive המשותף ומחלצים אותה. אם אין לכם גישה, פנו לנציג שלכם.
ב-Android Studio, פותחים פרויקט ומוסיפים את חבילת Google Play Services באמצעות SDK Manager.
מהספרייה של קובץ ה-ZIP, מעתיקים את libs/google_navigation_navmap.aar לספרייה app/libs של הפרויקט.

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

implementation(name: 'google_navigation_navmap', ext: 'aar')

מוסיפים את השורות הבאות ל-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'
       }
   }
}

הגדרת ה-build

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

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

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

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

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

הגדרות נדרשות ל-Navigation SDK
1. מגדירים את minSdkVersion ל-23 ומעלה.
2. מגדירים את targetSdkVersion ל-30 ומעלה.
3. מוסיפים dexOptions הגדרה שמגדילה את javaMaxHeapSize.
4. הגדרת המיקום של ספריות נוספות.
5. מוסיפים את repositories ואת dependencies ל-Navigation SDK.
6. מחליפים את מספרי הגרסאות בתלות בגרסאות העדכניות ביותר שזמינות.
הגדרות אופציונליות לקיצור משך זמן של תהליך build
- מפעילים צמצום קוד וצמצום משאבים באמצעות R8/ProGuard כדי להסיר קוד ומשאבים שלא נמצאים בשימוש מיחסי תלות. אם השלב של R8/ProGuard נמשך יותר מדי זמן, כדאי להפעיל multidex לעבודת פיתוח.
- מצמצמים את מספר התרגומים לשפות שנכללים בגרסה: מגדירים את הערך resConfigs לשפה אחת במהלך הפיתוח. בגרסת ה-build הסופית, מגדירים את resConfigs לשפות שבהן משתמשים בפועל. כברירת מחדל, Gradle כולל מחרוזות של משאבים לכל השפות שנתמכות על ידי Navigation SDK.

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

apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

ext {
    androidxVersion = "1.0.0"
    lifecycle_version = "1.1.1"
}

android {
    compileSdkVersion 30
    buildToolsVersion '28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 30
        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 {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
    flatDir {
        dirs 'libs'
    }
    google()

    // Required for accessing the Navigation SDK on Google's Maven repository.
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
}

dependencies {
    // Include the Google Navigation SDK
    implementation 'com.google.android.maps:navsdk:4.4.0'

    // The included AAR file under libs can be used instead of the Maven repository.
    // Uncomment the line below and comment out the previous dependency to use
    // the AAR file instead. Make sure that you add the AAR file to the libs directory.
    // implementation(name: 'google_navigation_navmap', ext: 'aar')

    // These dependencies are required for the Navigation SDK to function
    // properly at runtime.
    implementation 'org.chromium.net:cronet-fallback:69.3497.100'
    // Optional for Cronet users:
    // implementation 'org.chromium.net:cronet-api:69.3497.100'
    implementation 'androidx.appcompat:appcompat:${androidxVersion}'
    implementation 'androidx.cardview:cardview:${androidxVersion}'
    implementation 'com.google.android.material:material:${androidxVersion}'
    implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
    implementation 'androidx.preference:preference:${androidxVersion}'
    implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
    implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
    implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.google.android.datatransport:transport-api:2.2.0'
    implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
    implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
    implementation 'joda-time:joda-time:2.9.9'
    annotationProcessor 'androidx.annotation:annotation:1.1.0'
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}

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

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

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

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

ב-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")
    }
}

פותחים את קובץ 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")
}

אם אתם משתמשים ב-Android Studio, סנכרנו את הפרויקט עם Gradle.
פותחים את הקובץ local.properties בספרייה ברמת הפרויקט, ואז מוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.
```
MAPS_API_KEY=YOUR_API_KEY
```
אפשר להוסיף את מפתח ה-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

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

דרישות מינימליות לשימוש ב-Navigation SDK

הגדרת הפרויקטים: פרויקט במסוף Cloud ופרויקט Android

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

שימוש ב-Maven לגרסה 4.5 ואילך של Navigation SDK (מומלץ)

Gradle

Maven

שימוש ב-Maven ל-Navigation SDK בגרסה שלפני v4.5, או עם Driver SDK

Gradle

Maven

שימוש בחבילת AAR שהורדה (לא מומלץ)

הגדרת ה-build

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

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

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

Groovy

Kotlin

Groovy

Kotlin

Kotlin

Java

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

הגדרת הפרויקט – גרסה 4.99 וגרסאות קודמות