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

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

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

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

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

הגדרת מכשיר Android

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

• כדי להשתמש במכשיר Android, פועלים לפי ההוראות במאמר הפעלת אפליקציות במכשיר חומרה.
• כדי להשתמש באמולטור Android, אתם יכולים ליצור מכשיר וירטואלי ולהתקין את האמולטור באמצעות Device Manager שמגיע עם Android Studio.

יצירת פרויקט במפות Google ב-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:

   • מגדירים את השפה ל-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.

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

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

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

שלב 1: הגדרת הפרויקט

gcloud projects create "PROJECT"

שלב 2: מפעילים את ממשקי ה-API או ערכות ה-SDK

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

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

שלב 3: קבלת מפתח API

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

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

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

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

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

כדי להתקין את הפלאגין Secrets Gradle ל-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 לניהול הגרסאות.

   MAPS_API_KEY=YOUR_API_KEY

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

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

עיון בקוד

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

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

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

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

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

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

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

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

// 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))

      

// 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.

dependencies {

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

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

מידע נוסף על ניהול התלות במפות 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.