מדריך למתחילים של מפות Google ל-Android

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

המדריך למתחילים הזה מיועד למפתחים שמכירים את הפיתוח הבסיסי של Android באמצעות Kotlin או Java.

מידע על סביבת הפיתוח

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

הגדרת מכשיר Android

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

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

יצירת פרויקט של מפות Google ב-Android Studio

התהליך ליצירת פרויקט של מפות Google ב-Android Studio השתנה בגרסה Flamingo ואילך של Android Studio.

1. פותחים את Android Studio ולוחצים על New Project בחלון Welcome to Android Studio.

2. בחלון New Project, בקטע Phone and Tablet, בוחרים באפשרות No Activity ולוחצים על Next.

3. ממלאים את הטופס New Project:

   • מגדירים את Language (שפה) ל-Java או ל-Kotlin. שתי השפות נתמכות באופן מלא ב-SDK של מפות ל-Android. מידע נוסף על Kotlin זמין במאמר פיתוח אפליקציות ל-Android באמצעות Kotlin.

   • מגדירים את גרסת ה-SDK המינימלית לגרסה של SDK שתואמת למכשיר הבדיקה. צריך לבחור גרסה גבוהה יותר מהגרסה המינימלית שנדרשת על ידי Maps SDK לגרסה 19.0.x ל-Android, שהיא Android API ברמה 21 (Lollipop,‏ Android 5.0) ואילך. במאמר הערות המוצר מפורט המידע העדכני ביותר לגבי הדרישות לגבי גרסאות ה-SDK.

   • מגדירים את שפת תצורת ה-build ל-Kotlin DSL או ל-Groovy DSL. קטעי הקוד לשתי השפות של הגדרות ה-build מופיעים בתהליכים הבאים.

4. לוחצים על סיום.

   Android Studio מפעיל את Gradle ומאכלס את הפרויקט. פעולה זו עשויה להימשך זמן מה.

5. מוסיפים את הפעילות של צפיות במפות Google:

   1. לוחצים לחיצה ימנית על התיקייה app בפרויקט.

   2. בוחרים באפשרות חדש > Google > פעילות צפיות במפות Google.

      

   3. בתיבת הדו-שיח New Android Activity, מסמנים את התיבה Launcher Activity.

   4. בוחרים באפשרות סיום.

      למידע נוסף, ראו הוספת קוד מתבנית

6. בסיום ה-build, פותחים את הקובץ AndroidManifest.xml ואת הקובץ MapsActivity ב-Android Studio. יכול להיות שהפעילות תופיע בשם אחר, אבל זה השם שהגדרתם במהלך ההגדרה.

הגדרת הפרויקט ב-Google Cloud

כדי להשלים את שלבי ההגדרה הנדרשים במסוף Cloud, לוחצים על הכרטיסיות הבאות:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

הוספת מפתח ה-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")
       }
   }

   Groovy

   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")
   }

   Groovy

   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. שומרים את הקובץ.

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

8. שומרים את הקובץ.
9. בקובץ 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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other 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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    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"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

בדיקת הקוד

בודקים את הקוד שסופק בתבנית. כדאי לבדוק במיוחד את הקבצים הבאים בפרויקט ב-Android Studio.

קובץ הפעילות במפות Google

קובץ הפעילות של המפות הוא הפעילות הראשית של האפליקציה, והוא מכיל את הקוד לניהול ולתצוגה של המפה. כברירת מחדל, השם של הקובץ שמגדיר את הפעילות הוא MapsActivity.java. אם מגדירים את Kotlin כשפת האפליקציה, השם הוא MapsActivity.kt.

הרכיבים העיקריים של הפעילות במפות:

• האובייקט SupportMapFragment מנהל את מחזור החיים של המפה והוא רכיב ההורה של ממשק המשתמש של האפליקציה.

• האובייקט GoogleMap מספק גישה לנתוני המפה ולתצוגה שלה. זוהי הכיתה הראשית של ה-SDK של מפות ל-Android. במדריך לגבי אובייקטים במפה מוסבר בהרחבה על האובייקטים SupportMapFragment ו-GoogleMap.

• הפונקציה moveCamera ממרכזת את המפה לפי הקואורדינטות LatLng של סידני, אוסטרליה. ההגדרות הראשונות שצריך להגדיר כשמוסיפים מפה הן בדרך כלל מיקום המפה והגדרות המצלמה, כמו זווית הצפייה, כיוון המפה ורמת הזום. פרטים נוספים זמינים במדריך מצלמה ותצוגה.

• הפונקציה addMarker מוסיפה סמן לקואורדינטות של סידני. פרטים נוספים זמינים במדריך בנושא סמנים.

קובץ Gradle של המודול

קובץ המודול build.gradle.kts כולל את התלות הבאה במפות, שנדרשת על ידי ה-SDK של מפות Google ל-Android.

dependencies {

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

מידע נוסף על ניהול התלות במפות Google זמין במאמר ניהול גרסאות.

קובץ פריסה בפורמט XML

קובץ activity_maps.xml הוא קובץ הפריסה של ה-XML שמגדיר את המבנה של ממשק המשתמש של האפליקציה. הקובץ נמצא בספרייה res/layout. בקובץ activity_maps.xml מפורטים הרכיבים הבאים:

• tools:context מגדיר את פעילות ברירת המחדל של הפלח כ-MapsActivity, שמוגדר בקובץ הפעילות של מפות Google.
• android:name מגדיר את שם הכיתה של ה-Fragment כ-SupportMapFragment, שהוא סוג ה-Fragment שמשמש בקובץ הפעילות של המפות.

קובץ הפריסה של ה-XML מכיל את הקוד הבא:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

פריסה והפעלה של האפליקציה

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

כדי לפרוס ולהפעיל את האפליקציה:

1. ב-Android Studio, לוחצים על אפשרות התפריט Run (או על סמל לחצן ההפעלה) כדי להריץ את האפליקציה.
2. כשמוצגת בקשה לבחירת מכשיר, בוחרים באחת מהאפשרויות הבאות:
   • בוחרים את מכשיר Android שמחובר למחשב.
   • לחלופין, בוחרים בלחצן הבחירה Launch emulator ובוחרים את המכשיר הווירטואלי שהגדרתם.
3. לוחצים על אישור. Android Studio תפעיל את Gradle כדי ליצור את האפליקציה, ואז תציג את התוצאות במכשיר או במהדמ. יכול להיות שיחלפו כמה דקות עד שהאפליקציה תופעל.

השלבים הבאים

• הגדרת מפה: במסמך הזה מוסבר איך להגדיר את ההגדרות הראשוניות וההגדרות שפועלות במהלך זמן הריצה של המפה, כמו מיקום המצלמה, סוג המפה, רכיבי ממשק המשתמש והמחוות.

• הוספת מפה לאפליקציה ל-Android (Kotlin): בקודלאב הזה נסביר איך להוסיף לאפליקציה תכונות נוספות של SDK של מפות ל-Android.

• שימוש בספריית KTX של מפות Android: ספריית ההרחבות של Kotlin (KTX) הזו מאפשרת לכם ליהנות מכמה תכונות של שפת Kotlin בזמן השימוש ב-Maps SDK ל-Android.