מדריך למתחילים של מפות 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. שתי השפות נתמכות במלואן ב-Maps SDK ל-Android. מידע נוסף על Kotlin זמין במאמר פיתוח אפליקציות ל-Android באמצעות Kotlin.

   • מגדירים את Minimum 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}" />

   הערה: 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 יוצר חריגה.

10. ב-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"
    
        // 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.

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

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

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

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

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

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

קובץ המודול build.gradle.kts כולל את יחסי התלות הבאים במפות, שנדרשים ל-Maps SDK for 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 מגדיר את שם הכיתה של הפלח כ-SupportMapFragment, שהוא סוג הפלח שמשמש בקובץ הפעילות של מפות Google.

קובץ הפריסה של ה-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): בקודלאב הזה מוסבר איך ליצור אפליקציה שממחישה כמה תכונות נוספות של Maps SDK ל-Android.

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