דף זה תורגם על ידי Cloud Translation API.

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

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

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

‫Navigation SDK זמין דרך Google Maven Repository. אפשר להוסיף את ה-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.

אם יש לכם תלויות שמשתמשות ב-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, פותחים את הקובץ local.properties ומוסיפים את השורה android.useDeprecatedNdk=true.

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

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

הגדרות חובה ל-Navigation SDK
1. מגדירים את minSdkVersion ל-23 ומעלה.
2. מגדירים את הערך targetSdkVersion ל-34 ומעלה.
3. מוסיפים dexOptionsהגדרה שמגדילה את javaMaxHeapSize.
4. הגדרת המיקום של ספריות נוספות.
5. מוסיפים את repositories ואת dependencies ל-Navigation SDK.
6. מחליפים את מספרי הגרסאות בתלות בגרסאות העדכניות ביותר שזמינות.
הגדרות אופציונליות לקיצור זמן הבנייה
- הפעלה של כיווץ קוד וכיווץ משאבים באמצעות R8/ProGuard כדי להסיר קוד ומשאבים שלא נמצאים בשימוש מהתלות. אם השלב של R8/ProGuard נמשך יותר מדי זמן, כדאי להפעיל multidex לצורך עבודת פיתוח.
- מצמצמים את מספר התרגומים לשפות שנכללים בגרסה: מגדירים את הערך resConfigs לשפה אחת במהלך הפיתוח. בגרסה הסופית, צריך להגדיר את resConfigs לשפות שבהן משתמשים בפועל. כברירת מחדל, Gradle כולל מחרוזות של משאבים לכל השפות שנתמכות על ידי Navigation SDK.
הוספת desugaring לתמיכה ב-Java8
- אם אתם מפתחים את האפליקציה באמצעות פלאגין Android Gradle מגרסה 4.0.0 ואילך, הפלאגין מרחיב את התמיכה בשימוש במספר ממשקי API של שפת Java 8. מידע נוסף זמין במאמר בנושא תמיכה ב-desugaring ב-Java 8. אפשר לעיין בקטע הקוד לדוגמה של סקריפט הבנייה שבהמשך כדי לראות איך משתמשים באפשרויות של קומפילציה ותלות.
- מומלץ להשתמש ב-Gradle 8.4, בגרסה 8.3.0 של Android Gradle plugin ובספריית Desugar‏ com.android.tools:desugar_jdk_libs_nio:2.0.3. ההגדרה הזו תואמת ל-Navigation SDK ל-Android מגרסה 6.0.0 ואילך.
- צריך להפעיל את ספריית ה-Desugar עבור מודול app וכל מודול שתלוי ישירות ב-Navigation SDK.

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

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

Kotlin

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

מגניב

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

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

Kotlin

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

מגניב

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

בקובץ build.gradle.kts או build.gradle ברמת המודול, מוודאים שהערכים של targetSdk ו-compileSdk מוגדרים ל-34.
מסנכרנים את הפרויקט עם Gradle.
פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם. מומלץ לשמור את המפתח בקובץ הזה כי secrets.properties לא נכלל בבדיקה במערכת בקרת גרסאות.
הערה: אם הקובץ 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 לא נמצא, כדי שהגרסאות לא ייכשלו. מצב כזה יכול לקרות אם: אתם משכפלים את האפליקציה ממערכת בקרת גרסאות שבה לא מופיע secrets.properties, ועדיין לא יצרתם קובץ secrets.properties באופן מקומי כדי לספק את מפתח ה-API.
בקובץ AndroidManifest.xml, עוברים אל com.google.android.geo.API_KEY ומעדכנים את android:value attribute. אם התג <meta-data> לא קיים, יוצרים אותו כצאצא של התג <application>.
```
<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 זורק חריגה.

ב-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 same folder as the 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"
}

מגניב

secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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).

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

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

Gradle

Maven

Gradle

Maven

הגדרת ה-build

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

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

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

Kotlin

מגניב

Kotlin

מגניב

Kotlin

מגניב

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

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

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