הגדרה

בדף הזה מוסבר מה צריך לעשות כדי להתחיל לפתח באמצעות Maps 3D SDK ל-Android. תהליך ההגדרה כולל הגדרה של פרויקט ב-Google Cloud ו-API לשימוש עם ה-SDK, ואז הגדרה של פרויקט ב-Android Studio. לפני שמוסיפים את מפת התלת-ממד הראשונה לאפליקציה, צריך לבצע את השלבים הבאים.

דרישות מוקדמות

כדי להשתמש ב-Maps 3D SDK ל-Android, הפרויקט ומכשירי היעד צריכים לעמוד בדרישות הבאות:

• רמת API מינימלית: רמת API‏ 24 ב-Android‏ (Android 7.0) ומעלה. האפליקציה צריכה לטרגט ל-minSdk של 24 ומעלה.
• ‫Google Play Services: ערכת Maps 3D SDK ל-Android תלויה ב-Google Play Services. במכשירי היעד (ובאמולטורים עם Google APIs) צריכה להיות מותקנת אפליקציית Google Play Services.

הגדרת פרויקט בענן ב-Google Cloud ומפתח API

כדי להתחיל לפתח באמצעות Maps 3D SDK ל-Android, צריך להגדיר פרויקט בענן ב-Google Cloud ומפתח API לשימוש עם Maps 3D SDK ל-Android. לשם כך, צריך לבצע את השלבים הבאים:

שלב 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 שמתכננים להשתמש בהם בפרויקט.

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

כדי להפעיל ממשק API אחד או יותר או ערכת SDK אחת או יותר:

המסוף

1. כדי לראות את ממשקי ה-API וערכות ה-SDK של Google Maps Platform שאפשר להפעיל, נכנסים לדף Maps API Library במסוף Cloud:

   נכנסים לדף Maps API Library.

2. לוחצים על ה-API או ה-SDK שרוצים להפעיל.
   • אם בכפתור כתוב ENABLE, לוחצים עליו כדי להפעיל את ה-API או ה-SDK.
   • אם על הלחצן כתוב ניהול, ה-API או ה-SDK כבר מופעלים ואין צורך לבצע פעולה נוספת.
   • לחיצה על אחד מהלחצנים תציג את מרכז הבקרה של ה-API או ה-SDK. (כדי להסיר את ה-API או את ה-SDK מהפרויקט הזה, לוחצים על הלחצן השבתה).

Cloud SDK

הפקודה הבאה מפעילה את כל ממשקי ה-API של מפות Google, מסלולים ומקומות:

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

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

• gcloud services enable
• gcloud services disable

כדי להפעיל את ממשקי ה-API של הסביבה, משתמשים בפקודה הבאה:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

הערה: כשמפעילים את Places API, מופעלים גם ספריית המקומות, Maps JavaScript API, ‏Places SDK ל-Android ו-Places SDK ל-iOS.

שלב 3

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

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

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

המסוף

1. נכנסים לדף Google Maps Platform > פרטי כניסה.

   לדף 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

כדי להפעיל את ה-SDK, נכנסים לדף Maps 3D SDK ל-Android במסוף Google Cloud. מידע נוסף על השלבים האלה מופיע במאמר תחילת השימוש ב-Google Maps Platform.

הגדרת פרויקט ב-Android Studio

בקטע הזה מוסבר איך ליצור ולהגדיר פרויקט ב-Android Studio לשימוש עם Maps 3D SDK ל-Android.

חלק 1: הגדרת הפרויקט והגדרת Gradle

1. יוצרים פרויקט חדש ב-Android Studio באמצעות התבנית Empty Views Activity. בהגדרות הפרויקט, מגדירים את גרסת ה-SDK המינימלית לAPI 24 או לגרסה מתקדמת יותר.

2. אם אתם משתמשים ב-Git לניהול גרסאות, שנו את הקובץ .gitignore של הפרויקט כדי למנוע את הוספת קובץ הסודות לניהול הגרסאות:

   • בתיקיית השורש של הפרויקט, פותחים את הקובץ .gitignore.
   • מוסיפים את השורה הבאה:

   secrets.properties
   

3. מעדכנים את הקובץ build.gradle.kts ברמת הפרויקט:

   • בתיקיית השורש של הפרויקט, פותחים את הקובץ build.gradle.kts.
   • בבלוק plugins, מוסיפים את הפלאגין Secrets Gradle:

   plugins {
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
   }
   

4. מעדכנים את הקובץ gradle/libs.versions.toml:

   • פותחים את הקובץ gradle/libs.versions.toml, שבדרך כלל נמצא בספרייה gradle בתוך תיקיית השורש של הפרויקט.
   • בקטע [versions], מוסיפים את הגרסאות של ה-SDK ושל הפלאגין Secrets Gradle:

   # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
   maps3dSdk = "16.0.1"
   # See https://github.com/google/secrets-gradle-plugin/releases for available releases
   secretsGradlePlugin = "2.0.1"
   

   • בקטע [library], מוסיפים את ספריית ה-SDK:

   play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
   

   • בקטע [plugins], מוסיפים את הפלאגין Secrets Gradle:

   secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }
   

5. מעדכנים את הקובץ app/build.gradle.kts ברמת המודול:

   • פותחים את הקובץ build.gradle.kts ברמת המודול, שבדרך כלל נמצא בספרייה app.
   • בחלק העליון של הקובץ, מוסיפים את הפלאגין Secrets Gradle לבלוק plugins:

   plugins {
       alias(libs.plugins.android.application)
       alias(libs.plugins.kotlin.android)
       alias(libs.plugins.secrets.gradle.plugin) // Add this line
   }
   

   • בבלוק dependencies, מוסיפים את התלות ב-Google Play Services בשביל Maps 3D SDK ל-Android:

   dependencies {
       // ... other dependencies
       implementation(libs.play.services.maps3d) // Add this line
   }
   

   • בסוף הקובץ, מחוץ לבלוקים android ו-dependencies, מוסיפים את הגדרת הסודות:

   secrets {
       // Optionally specify a different filename 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"
   }
   

חלק 2: הוספת מפתח ה-API לפרויקט

1. יוצרים קובץ secrets.properties:

   • בתיקיית השורש של מודול האפליקציה (בדרך כלל התיקייה app), יוצרים קובץ חדש בשם secrets.properties.
   • מוסיפים את מפתח ה-API לקובץ:

   MAPS3D_API_KEY=YOUR_API_KEY_HERE
   

   הערה: הקפידו להחליף את YOUR_API_KEY_HERE במפתח ה-API שהגדרתם לשימוש עם Maps 3D SDK ל-Android.

2. יוצרים קובץ local.defaults.properties: - בתיקיית השורש של מודול האפליקציה, יוצרים קובץ חדש בשם local.defaults.properties. ‫- מוסיפים מפתח API של ברירת מחדל או placeholder לקובץ. אפשר להכניס את הקובץ הזה לניהול גרסאות:

   MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER
   

חלק 3: מעדכנים את הקובץ AndroidManifest.xml

1. פותחים את הקובץ app/src/main/AndroidManifest.xml.

2. בתוך התג <application>, לפני התג <activity>, מוסיפים את הרכיב <meta-data> הבא כדי להצהיר על מפתח ה-API:

   <application
       ...>
   
       <meta-data
           android:name="com.google.android.geo.maps3d.API_KEY"
           android:value="${MAPS3D_API_KEY}" />
   
       <activity
           ...>
       </activity>
   </application>
   

   במהלך תהליך הבנייה, התוסף Secrets Gradle יחליף את הפלייסולדר ${MAPS3D_API_KEY} במפתח מקובץ secrets.properties.

אתחול תצוגה פרוגרמטית (אופציונלי)

אם אתם מעדיפים להפעיל את תצוגת המפה באופן פרוגרמטי ולא בפריסות XML, השתמשו ב-Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

השלבים הבאים

אחרי שמגדירים פרויקט בענן ב-Google Cloud, מפתח API ופרויקט ב-Android Studio לשימוש עם Maps 3D SDK ל-Android, אפשר להוסיף מפה תלת-ממדית לאפליקציה.