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

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

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

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

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

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

הגדרה של מכשיר Android

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

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

  

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

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

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

2. בחלון New Project (פרויקט חדש), בקטגוריה טלפון וטאבלט, בוחרים באפשרות ללא פעילות ולוחצים על הבא.

3. ממלאים את הטופס פרויקט חדש:

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

   • מגדירים את Minimum SDK לגרסת SDK שתואמת למכשיר הבדיקה. עליך לבחור גרסה גבוהה יותר מהגרסה המינימלית הנדרשת על ידי SDK של מפות ל-Android גרסה 19.0.x, שהיא Android API ברמה 21 ("Lollipop"; Android 5.0) ומעלה. פרטים נוספים זמינים בנתוני הגרסה של את המידע העדכני ביותר על הדרישות של גרסת ה-SDK.

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

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

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

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

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

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

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

      

   3. בתיבת הדו-שיח פעילות חדשה ב-Android, בוחרים את תיבת הסימון פעילות מרכז האפליקציות.

   4. בוחרים באפשרות סיום.

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

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

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

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

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

שלב 1

המסוף

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

   לדף בורר הפרויקטים

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

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

Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

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

שלב 2

כדי להשתמש בפלטפורמה של מפות Google, עליכם להפעיל את ממשקי ה-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 > הדף 'פרטי כניסה'.

   כניסה לדף Credentials

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

• gcloud alpha services api-keys create

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

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

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

הערה: צריך לעיין ב פלאגין של Secrets Gradle ל-Android תיעוד ב-GitHub כדי לראות את דרישות המערכת העדכניות והוראות ההתקנה.

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

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

   מגניב

   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.

   מגניב

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

   Kotlin

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

3. בקובץ build.gradle ברמת המודול, מוודאים שהערכים targetSdk הערך של compileSdk מוגדר ל-34.
4. שומרים את הקובץ ואז לסנכרן את הפרויקט עם Gradle
5. פותחים את הקובץ secrets.properties בספרייה שברמה העליונה, ואז מוסיפים את באמצעות הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API שלכם. אחסון המפתח בקובץ הזה כי secrets.properties לא נכלל בבדיקה לניהול גרסאות המערכת.
   הערה: אם הקובץ secrets.properties לא קיים, יוצרים אותו באותה תיקייה שבה נמצא הקובץ local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. שומרים את הקובץ.

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

   הערה: צריך להזין את הקוד כמו שמוצג. לא להחליף DEFAULT_API_KEY מחליפים במפתח ה-API.

   MAPS_API_KEY=DEFAULT_API_KEY

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

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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 של מפות Google ל-Android. אובייקטים במפה מתאר את האובייקטים SupportMapFragment ו-GoogleMap מפורט.

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

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

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

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

dependencies {

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

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

השלבים הבאים

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

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

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