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

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

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

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

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

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

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

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

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

  

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

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

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

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

   • מגדירים את שפת תצורת build כ-Kotlin DSL או Graovy 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. יכול להיות שלפעילות שלכם יש שם אחר, אבל זה השם שהגדרתם במהלך ההגדרה.

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

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

שלב 2

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

   כניסה לדף Credentials

2. בדף Credentials, לוחצים על Create credentials > API key.
   תיבת הדו-שיח מפתח API שנוצר מציגה את מפתח ה-API החדש שיצרתם.
3. לוחצים על סגירה.
   מפתח ה-API החדש מופיע בדף Credentials בקטע API Keys.
   (חשוב לזכור להגביל את מפתח ה-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 ראו קובצי מאפייני Gradle.

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

הערה: במסמכי העזרה של הפלאגין של Secrets Gradle ל-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 שלכם.

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

קובץ הפעילות של המפות הוא הפעילות העיקרית של האפליקציה, ומכיל את הקוד לניהול ולהצגה של המפה. כברירת מחדל, הקובץ שמגדיר את הפעילות נקרא 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:19.0.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.