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

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

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

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

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

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

הגדרה של מכשיר Android

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

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

  

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

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

1. פותחים את Android Studio ולוחצים על Create New Project בחלון Welcome to Android Studio.

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

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

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

   • צריך להגדיר את הערך של Minimum SDK כגרסת SDK שתואמת למכשיר הבדיקה. עליכם לבחור גרסה מתקדמת יותר מהגרסה המינימלית הנדרשת על ידי ה-SDK של מפות Google ל-Android בגרסה 18.2.x, שהיא Android API ברמה 19 ("KitKat", Android 4.4) ואילך. בנתוני הגרסה יש מידע עדכני על הדרישות לגרסת ה-SDK.

     הערה: אם לא ברור לך באיזו גרסת SDK כדאי לבחור, אפשר ללחוץ על הקישור אשמח לעזרה בבחירה כדי להציג פרטי הפצה של ערכות SDK נתמכות של Android. לדוגמה, אם תבחרו באפשרות Android API Level 19 ("KitKat"; Android 4.4), האפליקציה שלכם אמורה לפעול ביותר מ-99% ממכשירי Android.

   • מגדירים את Build configuration Language (שפת ההגדרה) ל-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. לפעילות שלכם יכול להיות שם אחר, אבל זה השם שהגדרתם במהלך ההגדרה.

   אזהרה: הקובץ AndroidManifest.xml מכיל הוראות לקבלת מפתח API של מפות Google ואחר כך להוסיף אותו לקובץ local.properties. לא להוסיף את מפתח ה-API לקובץ local.properties. הפעולה הזו תאחסן את מפתח ה-API באופן פחות מאובטח. במקום זאת, יש לבצע את ההוראות במאמר הגדרת הפרויקט ב-Google Cloud כדי ליצור פרויקט ב-Cloud ולהגדיר מפתח API.

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

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

שלב 1

המסוף

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

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

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

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

שלב 2

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

המסוף

מפעילים את ה-SDK של מפות Google ל-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 > פרטי כניסה.

   לדף Credentials

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

Cloud SDK

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

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

• gcloud alpha services api-keys create

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

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

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

הערה: במסמכי התיעוד של Secrets Gradle Plugin for Android ב-GitHub מפורטות דרישות המערכת האחרונות והוראות ההתקנה.

כדי להתקין את הפלאגין Secrets Gradle ל-Android בפרויקט של מפות Google:

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

   מגניב

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

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

   מגניב

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

   Kotlin

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

3. בקובץ build.gradle ברמת המודול, מוודאים ש-targetSdk ו-compileSdk מוגדרים ל-34.
4. שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
5. פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API. אפשר לאחסן את המפתח בקובץ הזה כי אין אפשרות לבדוק את secrets.properties במערכת לניהול גרסאות.
   הערה: אם הקובץ secrets.properties לא קיים, צריך ליצור אותו באותה תיקייה שבה נמצא הקובץ local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. שומרים את הקובץ.

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

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

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

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.

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

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

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

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

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

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

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

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

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

dependencies {

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

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

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

השלבים הבאים

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

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

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