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

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

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

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

במסמך הזה מתוארת סביבת פיתוח שמשתמשת ב-Android Studio Hedgehog ובפלאגין של Android Gradle בגרסה 8.2.

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

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

1. בקובץ settings.gradle.kts ברמה העליונה, צריך לכלול את פורטל הפלאגין של Gradle, את מאגר ה-Maven של Google ואת מאגר ה-Maven המרכזי בבלוק pluginManagement. הבלוק pluginManagement צריך להופיע לפני כל הצהרה אחרת בסקריפט.

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

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

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

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

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation(libs.play.services.maps)
   }

   Groovy

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

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

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

6. בקובץ libs.versions.toml, מוסיפים את הקוד הבא:

   [versions]
   play-services-maps = "20.1.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

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

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

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

כדי להתקין את Secrets Gradle Plugin for Android ולשמור את מפתח ה-API:

1. ב-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
   }

2. פותחים את הקובץ 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'
   }

3. אם אתם משתמשים ב-Android Studio, מסנכרנים את הפרויקט עם Gradle.
4. פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API שלכם. חשוב להוסיף את secrets.properties לקובץ .gitignore (או להחריג אותו ממערכת ניהול גרסאות) כדי שלא תבצעו צ'ק-אין של מפתח ה-API לבקרת הגרסאות.

   MAPS_API_KEY=YOUR_API_KEY

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

6. בקובץ AndroidManifest.xml, עוברים אל com.google.android.geo.API_KEY ומעדכנים את המאפיין android:value באופן הבא:

   <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, כולל SDK של מפות ל-Android. כדי לשמור על תאימות לדורות קודמים, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הקודם הזה מאפשר אימות רק ל-Android Maps API v2. באפליקציה אפשר לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם מציינים את שניהם, ה-API זורק חריגה.

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

שלב 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, מוסיפים את הקוד הזה לרכיב manifest:

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

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

אם אתם מטרגטים גרסה 8.3 ואילך של Google Play Services SDK, לא צריך את ההרשאה 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

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

• כדי להשתמש במכשיר Android, פועלים לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
• כדי להשתמש באמולטור Android, אתם יכולים ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות Device Manager שמגיע עם Android Studio.

‫שלב 6: בודקים אם יש תמיכה ב-Play Services (אופציונלי)

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

השלבים הבאים

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