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

ליצור אפליקציית Android שמציגה מפה באמצעות תבנית Google Maps Views ל-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 APIs.

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

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

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

1. פותחים את Android Studio ולוחצים על פרויקט חדש בחלון ברוכים הבאים ל-Android Studio.

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

3. ממלאים את הטופס פרויקט חדש:

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

   • מגדירים את גרסת ה-SDK המינימלית לגרסת SDK שתואמת למכשיר הבדיקה. צריך לבחור גרסה שגבוהה מהגרסה המינימלית שנדרשת על ידי Maps SDK ל-Android גרסה 19.0.x, שהיא רמת 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, ‏ Android Studio פותח את הקבצים AndroidManifest.xml ו-MapsActivity. יכול להיות שהפעילות שלכם תהיה עם שם אחר, אבל זה השם שהגדרתם במהלך ההגדרה.

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

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

gcloud projects create "PROJECT"

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

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

   מגניב

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

   מגניב

   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. יוצרים את הקובץ local.defaults.properties בספרייה ברמה העליונה, באותה תיקייה שבה נמצא הקובץ secrets.properties, ואז מוסיפים את הקוד הבא.

   MAPS_API_KEY=DEFAULT_API_KEY

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

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

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

   מגניב

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

בדיקת הקוד

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

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

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

האלמנטים העיקריים של הפעילות במפות Google:

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

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

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

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

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

הקובץ Module build.gradle.kts כולל את התלות הבאה במפות, שנדרשת על ידי SDK של מפות ל-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, שמוגדר בקובץ הפעילות של המפות.
• ‫android:name מגדיר את שם המחלקה של המקטע ל-SupportMapFragment, שהוא סוג המקטע שמשמש בקובץ הפעילות של המפות.

קובץ הפריסה של ה-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 שמחובר למחשב.
   • לחלופין, בוחרים את לחצן הבחירה הפעלת אמולטור ובוחרים את המכשיר הווירטואלי שהגדרתם.
3. לוחצים על אישור. ‫Android Studio יפעיל את Gradle כדי לבנות את האפליקציה, ואז יציג את התוצאות במכשיר או באמולטור. יכול להיות שיחלפו כמה דקות עד שהאפליקציה תיפתח.

השלבים הבאים

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

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

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