מדריך למתחילים של מפות 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 של מפות ל-Android, צריך לפרוס אותה במכשיר Android או באמולטור של Android שמבוסס על Android בגרסה 6.0 ואילך וכולל את Google APIs.

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

  

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

ההליך ליצירת פרויקט במפות Google ב-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. ממלאים את הטופס New Project:

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

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

     הערה: אם אתם לא בטוחים איזו גרסת SDK לבחור, אתם יכולים ללחוץ על הקישור עזרה בבחירה כדי להציג מידע על ההפצה של ערכות SDK נתמכות ל-Android. לדוגמה, אם בוחרים באפשרות רמת 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 Maps Views Activity.

      

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

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

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

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

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

עיון בקוד

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

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

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

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

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

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

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

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

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

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

dependencies {

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

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

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

קובץ פריסה בפורמט XML

קובץ activity_maps.xml הוא קובץ פריסת XML שמגדיר את המבנה של ממשק המשתמש של האפליקציה. הקובץ נמצא בספרייה res/layout. בקובץ activity_maps.xml מצהירים על מקטע שכולל את הרכיבים הבאים:

• ‫tools:context מגדיר את הפעילות שמוגדרת כברירת מחדל של הפריט כ-MapsActivity, שמוגדר בקובץ הפעילות של המפה.
• ‫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 של מפות ל-Android.

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