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

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

הערה: במדריך למתחילים הזה נעשה שימוש בתבנית Google Maps Views Activity, שיוצרת פריסת XML עם SupportMapFragment. אם אתם מפתחים את ממשק המשתמש באמצעות Jetpack Compose, עיינו במאמר בנושא ספריית Maps Compose.

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

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

מומלץ להשתמש בגרסה היציבה העדכנית של Android Studio ושל הפלאגין של Android Gradle.

הערה: אם בסביבת הפיתוח שלכם מותקנת גרסה אחרת של Android Studio או Gradle, יכול להיות שתצטרכו לשנות את השלבים בהתאם לסביבה. מידע נוסף על גרסאות של Android Studio ו-Gradle זמין במאמר תאימות של הפלאגין של Android Gradle ו-Android Studio.

הגדרת מכשיר Android

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

• כדי להשתמש במכשיר Android, פועלים לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
• כדי להשתמש באמולטור Android, אתם יכולים ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות Device Manager שמגיע עם Android Studio.
  הערה: אם אתם בוחרים להשתמש באמולטור של Android, ודאו שאתם בוחרים פרופיל מכשיר עם סמל Google Play, , שמוצג בעמודה Play. הסמל הזה מציין שהפרופילים האלה תואמים באופן מלא ל-CTS ויכולים להשתמש בתמונות מערכת שכוללות את אפליקציית חנות Play:

  

  תיבת הדו-שיח Add Device ב-Device Manager ב-Android Studio, שבה מוצגים פרופילים של מכשירים וירטואליים עם סמל Google Play בעמודה Play.

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

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

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

   הערה: אם מתחילים מתבנית ברירת המחדל Empty Activity (Jetpack פיתוח נייטיב) במקום No Activity ומוסיפים מאוחר יותר Google Maps Views Activity, האפליקציה MapsActivity (AppCompatActivity) קורסת בזמן ההפעלה עם IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity כי תבנית פיתוח הנייטיב מגדירה את העיצוב הראשי ב-res/values/themes.xml כ-android:Theme.Material.Light.NoActionBar. כדי למנוע את הקריסה הזו, צריך לעדכן את parent של העיצוב ב-res/values/themes.xml ל-Theme.AppCompat.DayNight.NoActionBar ולוודא ש-.MapsActivity מוגדר כפעילות MAIN/LAUNCHER ב-AndroidManifest.xml.

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

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

   • מגדירים את Minimum SDK (גרסת SDK מינימלית) לגרסת SDK שתואמת למכשיר הבדיקה. צריך לבחור גרסה גבוהה יותר מהגרסה המינימלית שנדרשת על ידי Maps SDK ל-Android בגרסה 20.0.x, שהיא Android API ברמה 23 ("Marshmallow"; Android 6.0) ומעלה. בנתוני הגרסה מפורט המידע העדכני ביותר על הדרישות של גרסת ה-SDK.

     הערה: אם אתם לא בטוחים באיזו גרסת SDK לבחור, לחצו על הקישור Help me choose כדי להציג מידע על ההפצה של ערכות Android SDK נתמכות. לדוגמה, אם בוחרים באפשרות רמת API 23 של Android ("Marshmallow"; Android 6.0), האפליקציה אמורה לפעול ביותר מ-99% ממכשירי Android.

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

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

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

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

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

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

      

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

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

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

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

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

   שימו לב: הפרויקט שנוצר על ידי התבנית Google Maps Views Activity לא יפעל בלי הגדרות נוספות. למרות שהתבנית מוסיפה את הפלאגין Secrets Gradle ל-Android אל libs.versions.toml ואל build.gradle.kts, היא לא מגדירה את secrets.properties. במקום זאת, היא מוסיפה פלייסהולדר של YOUR_API_KEY ישירות אל AndroidManifest.xml (עם הערות מדור קודם שמפנות אל local.properties). אל תדביקו את מפתח ה-API ישירות אל AndroidManifest.xml ואל תוסיפו אותו אל local.properties. במקום זאת, פועלים לפי ההוראות במאמרים הגדרת הפרויקט ב-Google Cloud והוספת מפתח ה-API לאפליקציה כדי לאחסן את MAPS_API_KEY בקובץ secrets.properties, מגדירים את הבלוק secrets בקובץ Gradle ברמת המודול ומגדירים את android:value="${MAPS_API_KEY}" ב-AndroidManifest.xml.

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

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

שלב 1

המסוף

1. במסוף Google Cloud, בדף לבחירת הפרויקט לוחצים על Create Project כדי ליצור פרויקט חדש ב-Cloud.

   כניסה לדף לבחירת הפרויקט

2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. מוודאים שהחיוב מופעל בפרויקט.

   ב-Google Cloud יש תקופת ניסיון בחינם. תקופת הניסיון מסתיימת אחרי 90 יום או אחרי שהחשבון צבר חיובים בסך 300$, המוקדם מביניהם. אפשר לבטל את המינוי בכל שלב. מידע נוסף זמין במאמרים זיכויים בחשבון לחיוב וחיוב.

Cloud SDK

gcloud projects create "PROJECT"

מידע נוסף על Google Cloud SDK , התקנת Cloud SDK , והפקודות הבאות:

• gcloud projects create

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

שלב 2

כדי להשתמש ב-Google Maps Platform, צריך להפעיל את ממשקי ה-API או ערכות ה-SDK שבהם רוצים להשתמש בפרויקט.

המסוף

הפעלת SDK של מפות ל-Android

Cloud SDK

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

מידע נוסף על Google Cloud SDK , התקנת Cloud SDK , והפקודות הבאות:

• gcloud services enable
• gcloud services disable

שלב 3

השלב הזה מתייחס רק לתהליך היצירה של מפתח ה-API. אם אתם משתמשים במפתח ה-API בסביבת הייצור, מומלץ מאוד להגביל את מפתח ה-API. מידע נוסף זמין בדף שימוש במפתחות API הספציפי למוצר.

מפתח ה-API הוא מזהה ייחודי שמאמת בקשות שמשויכות לפרויקט שלכם לצורכי שימוש וחיוב. צריך להיות לפחות מפתח API אחד שמשויך לפרויקט.

כך יוצרים מפתח API:

המסוף

1. נכנסים לדף Google Maps Platform > Credentials.

   כניסה לדף Credentials

2. בדף Credentials, לוחצים על Create credentials > מפתח API.
   בתיבת הדו-שיח API key created מוצג מפתח ה-API החדש שיצרתם.
3. לוחצים על סגירה.
   מפתח ה-API החדש מופיע בדף Credentials בקטע API keys.
   (חשוב לזכור להגביל את מפתח ה-API לפני שמשתמשים בו בסביבת הייצור).

Cloud SDK

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

מידע נוסף על Google Cloud SDK , התקנת Cloud SDK , והפקודות הבאות:

• gcloud services api-keys create

הוספת מפתח ה-API לאפליקציה

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

כדי לפשט את המשימה הזו, מומלץ להשתמש בפלאגין Secrets Gradle ל-Android.

כדי להתקין את Secrets Gradle Plugin for Android ולשמור את מפתח ה-API:

1. ב-Android Studio, פותחים את הקובץ build.gradle.kts או build.gradle ברמה העליונה ומוסיפים את הקוד הבא לבלוק plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. פותחים את הקובץ build.gradle.kts או build.gradle ברמת המודול ומוסיפים את הקוד הבא לרכיב plugins.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. אם אתם משתמשים ב-Android Studio, סנכרנו את הפרויקט עם Gradle.
4. פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API שלכם. חשוב להוסיף את secrets.properties לקובץ .gitignore (או להחריג אותו בדרך אחרת ממערכת ניהול הגרסאות) כדי לא להכניס את מפתח ה-API לניהול הגרסאות.
   הערה: אם הקובץ secrets.properties לא קיים, צריך ליצור אותו באותה תיקייה שבה נמצא הקובץ local.properties.

   MAPS_API_KEY=YOUR_API_KEY

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

   הערה: צריך להזין את הקוד בדיוק כמו שהוא מופיע. אל תחליפו את הערך DEFAULT_API_KEY במפתח ה-API שלכם.

   MAPS_API_KEY=DEFAULT_API_KEY

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

6. בקובץ AndroidManifest.xml, עוברים אל com.google.android.geo.API_KEY ומעדכנים את המאפיין android:value באופן הבא:

   <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 מקפיץ הודעת שגיאה.

7. ב-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 root directory (the same folder as the root 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"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

הערה: אם Logcat מדווח על E/Google Maps Android API: Authorization failure או אם משבצות המפה לא נטענות, צריך לוודא ש-SDK של מפות ל-Android מופעל בפרויקט בענן ב-Google Cloud, שמפתח ה-API ב-AndroidManifest.xml הממוזג תקף, ואם מפתח ה-API משתמש בהגבלות על אפליקציות ל-Android, ששם החבילה של הפרויקט (למשל com.example.myfirstmapsapp) וטביעת האצבע מסוג SHA-1 של מאגר מפתחות החתימה (למשל ~/.android/debug.keystore) נוספו לאפליקציות ל-Android שמפתח ה-API מאפשר להן גישה ב-Google Cloud.

עיון בקוד

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

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

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

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

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

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

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

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

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

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

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

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Groovy

dependencies {

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

אם הפרויקט משתמש בקטלוג גרסאות של Gradle‏ (gradle/libs.versions.toml), צריך להגדיר את התלות של play-services-maps ב-libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

הערה: הגרסה המדויקת עשויה להשתנות בהתאם לגרסה הנוכחית של ה-SDK של מפות Google ל-Android.

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

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