איך מגדירים פרויקט Android Studio

בדף הזה מוסבר איך להגדיר פרויקט ב-Android Studio כדי להשתמש ב-Maps SDK for Android בלי להשתמש בתבנית של מפות Google שמפורטת במדריך לתחילת העבודה.

תבנית מפות Google מגדירה ומוסיפה באופן אוטומטי מפה בסיסית לפרויקט חדש ב-Android Studio. עם זאת, אפשר גם להוסיף מפה לפרויקט Android שמשתמש בתבנית אחרת של Android Studio. כדי לעשות זאת, צריך להגדיר את הפרויקט באופן ידני ואז להוסיף את המפה.

שלב 1: הגדרת Android Studio

במסמך הזה מתוארת סביבת פיתוח באמצעות Android Studio Hedgehog וAndroid Gradle plugin בגרסה 8.2.

הערה: אם בסביבת הפיתוח שלכם נעשה שימוש בגרסה אחרת של Android Studio או Gradle, יכול להיות שתצטרכו לשנות את השלבים בהתאם לגרסאות האלה. מידע נוסף על גרסאות Android Studio ו-Gradle זמין במאמר בנושא תאימות של הפלאגין של Android Gradle ו-Android Studio.

שלב 2. הגדרת ה-SDK

הספרייה Maps SDK for Android זמינה דרך מאגר Maven של Google. כדי להוסיף את ה-SDK לאפליקציה:

1. בקובץ settings.gradle.kts ברמה העליונה, כוללים את Gradle plugin portal, Google Maven repository, ו-Maven central repository בקטע pluginManagement. הבלוק pluginManagement חייב להופיע לפני כל הצהרה אחרת בסקריפט.

   pluginManagement {
       repositories {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

2. בקובץ settings.gradle.kts ברמה העליונה, צריך לכלול את מאגר Maven של Google ואת מאגר Maven המרכזי בתוך הבלוק dependencyResolutionManagement:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. בקובץ build.gradle.kts או build.gradle ברמת המודול, מוסיפים את התלות ב-Google Play Services עבור Maps SDK ל-Android.

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation("com.google.android.gms:play-services-maps:19.0.0")
   }

   מגניב

   dependencies {
   
       // Maps SDK for Android
       implementation "com.google.android.gms:play-services-maps:19.0.0"
   }

4. בקובץ build.gradle.kts או build.gradle ברמת המודול, מגדירים את compileSdk ואת minSdk לערכים הבאים:
   הערה: חשוב לוודא שהערך של compileSdk הוא 34 ומעלה, ושהערך של minSdk הוא 21 ומעלה.

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 21
           // ...
       }
   }

   מגניב

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 21
           // ...
       }
   }

5. בקטע buildFeatures של הקובץ build.gradle.kts או build.gradle ברמת המודול, מוסיפים את המחלקה BuildConfig, שבה אפשר להשתמש כדי לגשת לערכי מטא-נתונים שמוגדרים בהמשך התהליך הזה:

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

   מגניב

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

שלב 3: מוסיפים את מפתח ה-API לפרויקט

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

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

הערה: במאמר Secrets Gradle Plugin for Android ב-GitHub מפורטות דרישות המערכת העדכניות והוראות ההתקנה.

כדי להתקין את הפלאגין 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 לא נכלל בבדיקה במערכת בקרת גרסאות.
   הערה: אם הקובץ secrets.properties לא קיים, צריך ליצור אותו באותה תיקייה שבה נמצא הקובץ local.properties.

   MAPS_API_KEY=YOUR_API_KEY

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

   הערה: מזינים את הקוד בדיוק כמו שהוא מוצג. אל תחליפו את הערך DEFAULT_API_KEY במפתח ה-API שלכם.

   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, כולל Maps SDK for 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"
   }
           

שלב 4: מעדכנים את קובץ המניפסט של האפליקציה

בקטע הזה מוסבר אילו הגדרות צריך להוסיף לקובץ AndroidManifest.xml.

מספר הגרסה של Google Play Services

מוסיפים את ההצהרה הבאה לרכיב application. הפעולה הזו מטמיעה את הגרסה של Google Play Services שהאפליקציה קומפלה איתה.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

הרשאת מיקום

אם האפליקציה שלכם צריכה לגשת למיקום של המשתמש, אתם צריכים לבקש את הרשאת המיקום בקובץ AndroidManifest.xml. האפשרויות הן ACCESS_FINE_LOCATION, שמאפשרת לקבל את המיקום המדויק של המכשיר, ו- ACCESS_COARSE_LOCATION, שמאפשרת לקבל מיקום פחות מדויק. פרטים נוספים זמינים במדריך בנושא נתוני מיקום.

הערה: האפשרות התחלה מהירה מופעלת ב-ACCESS_FINE_LOCATION.

כדי לבקש את ההרשאה ACCESS_FINE_LOCATION, מוסיפים את הקוד הזה לרכיב manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

הרשאה לניהול אחסון חיצוני

אם אתם מכוונים לגרסה 8.3 ואילך של ערכת ה-SDK של שירותי Google Play, לא צריך את ההרשאה WRITE_EXTERNAL_STORAGE. אם אתם מכוונים לגרסאות קודמות של Google Play services SDK, אתם צריכים לבקש את ההרשאה WRITE_EXTERNAL_STORAGE ברכיב manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

ספריית Apache HTTP מדור קודם

אם אתם משתמשים בגרסה com.google.android.gms:play-services-maps:16.0.0 ומטה והאפליקציה שלכם מטרגטת רמת API‏ 28 (Android 9.0) ומעלה, אתם צריכים לכלול את ההצהרה הבאה ברכיב <application> של AndroidManifest.xml. אחרת, מדלגים על ההצהרה הזו.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

שלב 5: הגדרת מכשיר Android

כדי להריץ אפליקציה שמשתמשת ב-Maps SDK ל-Android, צריך לפרוס אותה במכשיר Android או באמולטור Android שמבוסס על Android בגרסה 5.0 ואילך וכולל את Google APIs.

• כדי להשתמש במכשיר Android, פועלים לפי ההוראות במאמר הרצת אפליקציות במכשיר חומרה.
• כדי להשתמש באמולטור Android, אפשר ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות Android Virtual Device (AVD) Manager שמגיע עם Android Studio.
  הערה: אם בחרתם להשתמש באמולטור של Android, ודאו שבחרתם מכשיר עם סמל Play, , שמוצג בעמודה חנות Play. הסמל הזה מציין שהפרופילים האלה תואמים באופן מלא ל-CTS ויכולים להשתמש בתמונות מערכת שכוללות את אפליקציית חנות Play:

  

שלב 6: אפשר לבדוק אם יש תמיכה ב-Play Services

כדי להשתמש ב-Maps SDK for Android, צריך להתקין את Google Play Services במכשיר שבו פורסים את האפליקציה. ‫Google מספקת שיטה שאפשר להפעיל מהאפליקציה כדי לבדוק את הזכאות. מידע נוסף זמין במאמר בנושא בדיקה אם Google Play Services מותקן.

השלבים הבאים

אחרי שמגדירים את הפרויקט, אפשר להוסיף מפה.