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

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

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

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

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

הגדרת מכשיר Android

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

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

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

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

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

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

  3. ממלאים את הטופס New Project:

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

    • מגדירים את גרסת ה-SDK המינימלית לגרסה של SDK שתואמת למכשיר הבדיקה. צריך לבחור גרסה גבוהה יותר מהגרסה המינימלית שנדרשת על ידי Maps SDK לגרסה 19.0.x ל-Android, שהיא Android API ברמה 21 (Lollipop,‏ Android 5.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, פותחים את הקובץ AndroidManifest.xml ואת הקובץ MapsActivity ב-Android Studio. יכול להיות שהפעילות תופיע בשם אחר, אבל זה השם שהגדרתם במהלך ההגדרה.

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

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

שלב 1

המסוף

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

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

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

שלב 2

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

המסוף

הפעלת SDK של מפות ל-Android

Cloud SDK

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

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

שלב 3

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

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

כך יוצרים מפתח API:

המסוף

  1. עוברים לדף פלטפורמת מפות Google > פרטי כניסה.

    כניסה לדף Credentials

  2. בדף Credentials, לוחצים על Create credentials > API key.
    תיבת הדו-שיח API key created מציגה את מפתח ה-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 ועל הפקודות הבאות:

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

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

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

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

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

    Kotlin

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

    Groovy

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}
  2. פותחים את הקובץ build.gradle.kts או build.gradle ברמת המודול ומוסיפים את הקוד הבא לאלמנט plugins.

    Kotlin

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

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. בקובץ build.gradle.kts או build.gradle ברמת המודול, מוודאים שהערך של targetSdk ו-compileSdk מוגדר ל-34.
  4. שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
  5. פותחים את הקובץ secrets.properties בתיקיית הרמה העליונה ומוסיפים את הקוד הבא. מחליפים את הערך YOUR_API_KEY במפתח ה-API שלכם. מומלץ לשמור את המפתח בקובץ הזה כי secrets.properties לא נכלל במערכת בקרת הגרסאות. 
    MAPS_API_KEY=YOUR_API_KEY
  6. שומרים את הקובץ.

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

    MAPS_API_KEY=DEFAULT_API_KEY

    מטרת הקובץ הזה היא לספק מיקום גיבוי למפתח ה-API, כדי למנוע כשל ב-build אם הקובץ secrets.properties לא נמצא. מצב כזה יכול לקרות אם משכפלים את האפליקציה ממערכת בקרת גרסאות שמשמיטה את 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}" />

    הערה: com.google.android.geo.API_KEY הוא שם המטא-נתונים המומלץ למפתח ה-API. אפשר להשתמש במפתח עם השם הזה כדי לבצע אימות במספר ממשקי API שמבוססים על מפות Google בפלטפורמת Android, כולל Maps SDK for Android. מטעמי תאימות לאחור, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הקודם מאפשר אימות רק ל-Android Maps API v2. אפליקציה יכולה לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם מציינים את שניהם, ה-API יוצר חריגה.

  10. ב-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 same folder as the 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"

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

    Groovy

    secrets {
    // To add your Maps API key to this project:
    // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"

    // 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 של מפות ל-Android. במדריך לגבי אובייקטים במפה מוסבר בהרחבה על האובייקטים SupportMapFragment ו-GoogleMap.

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

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

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

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

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

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

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

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

  • tools:context מגדיר את פעילות ברירת המחדל של הפלח כ-MapsActivity, שמוגדר בקובץ הפעילות של מפות Google.
  • android:name מגדיר את שם הכיתה של ה-Fragment כ-SupportMapFragment, שהוא סוג ה-Fragment שמשמש בקובץ הפעילות של המפות.

קובץ הפריסה של ה-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): בקודלאב הזה נסביר איך להוסיף לאפליקציה תכונות נוספות של SDK של מפות ל-Android.

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