הגדרת הפרויקט – גרסה 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. למפתח יכולים להיות משויכים יותר מפרויקט פיתוח אחד. אם כבר יש לכם פרויקט במסוף, אתם יכולים להוסיף מפתח לפרויקט הנוכחי.

כדי להגדיר

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

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

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

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

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

  1. מוסיפים את התלות הבאה להגדרות של 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

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

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

  2. מוסיפים את יחסי התלות הבאים להגדרות של 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).

  1. מורידים את הגרסה העדכנית של Navigation SDK מGoogle Drive המשותף ומחלצים אותה. אם אין לכם גישה, פנו לנציג שלכם.

  2. ב-Android Studio, פותחים פרויקט ומוסיפים את חבילת Google Play services באמצעות SDK Manager.

  3. מהספרייה של קובץ ה-ZIP, מעתיקים את libs/google_navigation_navmap.aar לספרייה app/libs של הפרויקט.

  4. מוסיפים את הקוד הבא לקובץ 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

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

    הגדרות אופציונליות לקיצור זמן הבנייה

    • הפעלה של כיווץ קוד וכיווץ משאבים באמצעות R8/ProGuard כדי להסיר קוד ומשאבים שלא נמצאים בשימוש מהתלות. אם השלב של R8/ProGuard נמשך יותר מדי זמן, כדאי להפעיל multidex לצורך עבודת פיתוח.
    • מצמצמים את מספר התרגומים לשפות שנכללים בגרסה: מגדירים את הערך resConfigs לשפה אחת במהלך הפיתוח. בגרסה הסופית, צריך להגדיר את resConfigs לשפות שבהן משתמשים בפועל. כברירת מחדל, Gradle כולל מחרוזות של משאבים לכל השפות שנתמכות על ידי Navigation SDK.

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

  1. ב-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"     } }
  2. פותחים את הקובץ 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' }
  3. בקובץ build.gradle.kts או build.gradle ברמת המודול, מוודאים שהערכים של targetSdk ו-compileSdk מוגדרים ל-34.
  4. מסנכרנים את הפרויקט עם Gradle.
  5. פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם. מומלץ לשמור את המפתח בקובץ הזה כי secrets.properties לא נכלל בבדיקה במערכת בקרת גרסאות. 
    MAPS_API_KEY=YOUR_API_KEY

  6. יוצרים את הקובץ local.defaults.properties בספרייה ברמה העליונה, באותה תיקייה שבה נמצא הקובץ secrets.properties, ואז מוסיפים את הקוד הבא.

    MAPS_API_KEY=DEFAULT_API_KEY

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

  7. בקובץ 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 זורק חריגה.

  8. ב-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