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

‫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 באזור Application restrictions.
לוחצים על Add the package name and fingerprint, ואז מזינים את שם החבילה של פרויקט הפיתוח ואת טביעת האצבע מסוג SHA-1 של המפתח הזה.
לוחצים על שמירה.

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

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

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

הדוגמה הבאה משתמשת במאגר 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>

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

<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 לפני גרסה 4.5, או עם Driver SDK

‫Navigation SDK ימשיך להיות זמין באמצעות מאגר Maven המקורי בשאר גרסאות v4. זו אותה ספרייה עם אותם עדכונים כמו בגרסה שלמעלה, והיא מספקת תאימות ל-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>

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

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

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

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

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

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

Gradle

Maven

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

Gradle

Maven

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

הגדרת ה-build

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

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

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

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Java

Kotlin

Groovy

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

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