איך מגדירים פרויקט 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

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

1. בקובץ settings.gradle.kts ברמה העליונה, צריך לכלול את פורטל הפלאגין של Gradle, את מאגר ה-Maven של Google ואת מאגר ה-Maven המרכזי בקטע 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(libs.play.services.maps)
   }

   Groovy

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

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

   Kotlin

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

   Groovy

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

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 = "19.2.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

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

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

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

כדי להתקין את הפלאגין Secrets Gradle ל-Android ולאחסן את מפתח ה-API:

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

   Groovy

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

   Kotlin

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

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

   Groovy

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

   Kotlin

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

3. אם אתם משתמשים ב-Android Studio, מסנכרנים את הפרויקט עם Gradle.
4. פותחים את הקובץ local.properties בספרייה ברמת הפרויקט, ואז מוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.

   MAPS_API_KEY=YOUR_API_KEY

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

שלב 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 של מפות Google ל-Android, צריך לפרוס אותה במכשיר Android או באמולטור Android שמבוסס על Android 5.0 ומעלה וכולל את ממשקי ה-API של Google.

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

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

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

השלבים הבאים

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