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

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

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

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

המדריך למתחילים הזה פותח באמצעות Android Studio קיפוד וגם 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. ממלאים את הטופס פרויקט חדש:

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

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

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

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

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

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

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

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

      

   3. בתיבת הדו-שיח פעילות חדשה ב-Android, בוחרים את תיבת הסימון פעילות מרכז האפליקציות.

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

   מגניב

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

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

   MAPS_API_KEY=DEFAULT_API_KEY

   מטרת הקובץ הזה היא לספק מיקום לגיבוי של מפתח ה-API אם קובץ secrets.properties לא נמצא כדי שגרסאות ה-build לא ייכשלו. הדבר יכול להתרחש אם משכפלים את האפליקציה ממערכת לניהול גרסאות שמושמטת מ-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.

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

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

השלבים הבאים

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

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

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