מדריך למתחילים של מפות 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:

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

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

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

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

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

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

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

    2. בוחרים באפשרות חדש > Google ‏ > Google Maps Views Activity.

      הוספת פעילות במפות Google.

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

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

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

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

הגדרת הפרויקט ב-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 , והפקודות הבאות:

שלב 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 , והפקודות הבאות:

שלב 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 , והפקודות הבאות:

הוספת מפתח ה-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

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

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

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

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

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

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

Kotlin

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

Java

// 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 ברמת המודול כולל את התלות הבאה במפות, שנדרשת על ידי SDK של מפות ל-Android.

Kotlin

dependencies {

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

Groovy

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.