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

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

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

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

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

הגדרת מכשיר Android

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

• כדי להשתמש במכשיר 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, כדי למנוע כשל ב-build אם הקובץ 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, כולל Maps SDK for 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.

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

• האובייקט 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.