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

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

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

  

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

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

1. פותחים את Android Studio ולוחצים על New Project (פרויקט חדש) בחלון Welcome to 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.

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

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

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

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

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

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

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

      

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

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

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

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

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

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

המסוף

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

   לדף Credentials

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

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

כדי להתקין את הפלאגין Secrets Gradle ל-Android ולאחסן את מפתח ה-API:

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

   Groovy

   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.

   Groovy

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

   Kotlin

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

3. אם אתם משתמשים ב-Android Studio, מסנכרנים את הפרויקט עם Gradle.
4. פותחים את הקובץ local.properties בספרייה ברמת הפרויקט, ואז מוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם.

   MAPS_API_KEY=YOUR_API_KEY

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

בדיקת הקוד

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

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

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

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

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

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

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

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

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

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

dependencies {

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

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

השלבים הבאים

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

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

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